@vercel/build-utils 14.10.2 → 14.12.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @vercel/build-utils
 
+## 14.12.0
+
+### Minor Changes
+
+- 6e68e60: Add `onMiss` to `Prerender`.
+
+  ```ts
+  onMiss?: 'sync' | 'dynamic';
+  ```
+
+  Declares how a request is served when no prerendered output is available for
+  it yet. Absent means `sync`: block the response on rendering it. `dynamic`
+  serves the request dynamically while the static shell is regenerated in the
+  background. The value is carried unvalidated so an unknown mode cannot fail
+  a deploy.
+
+## 14.11.0
+
+### Minor Changes
+
+- 888f59e: Define an optional builder-owned development manifest for function identities, local invocation targets, trigger metadata, and native schedule definitions. Conventional functions can use host-owned per-entrypoint discovery; frameworks can override it. The host retains ownership of processes, readiness, and registration reconciliation.
+
+### Patch Changes
+
+- 7eb63c0: Accept runtime-specific schedule entrypoints and provide build plumbing for lowering dedicated entrypoints to function targets. All schedule entrypoints must use one runtime, including for static frameworks and `framework: null`. Entrypoints must also match the runtime of frameworks that own one (Next.js, FastAPI, Express). The builder contract still supports multiple entrypoints per function for future runtimes.
+
 ## 14.10.2
 
 ### Patch Changes

package/DEV_MANIFEST.md

@@ -0,0 +1,84 @@
+# Development manifest
+
+Builders may export `getDevManifest`, typed as `GetDevManifest`, independently
+of `build()` and `startDevServer()`. It describes deployment function identities,
+their local invocation targets, and optional native schedule definitions.
+Queues and Schedules share the function registry instead of separate discovery APIs.
+
+## Inputs
+
+- `workPath`: absolute project or service root.
+- `build`: the original builder entry before source expansion or filtering for a
+  framework development command; its source is relative to `workPath`.
+- `files`: real source paths relative to `workPath`, using forward slashes,
+  respecting ignore rules and excluding synthetic aliases.
+- `config`: resolved, builder-scoped authored configuration, including functions.
+  Do not independently reload vercel.json; the host may resolve vercel.ts or
+  partition function patterns between builders. Explicitly empty maps stay empty.
+- `env`: effective development environment, including injected resources.
+  Do not mutate inputs or log credentials.
+
+For services, paths are service-root-relative and `config.serviceName` supplies
+production consumer scoping where applicable.
+
+## Functions and invocation
+
+Every `DevFunction` has a deployment `outputPath` with no leading slash or
+`.func` suffix. It is the identity referenced by a Schedule's `target.function`,
+not necessarily the source filename or the public URL. `sourceFile` optionally
+identifies the original source for source-backed functions.
+
+`invocation` is one of:
+
+- `http`: a root-relative pathname in the owning framework dev server, including
+  its base path. No origin, query string, or fragment. The host supplies the origin.
+- `entrypoint`: a discrete builder entrypoint relative to `workPath`. The host
+  selects that function directly, without re-entering public routing, redirects,
+  rewrites, or an unrelated catch-all. This is also the host's conventional
+  per-entrypoint fallback target.
+
+Functions without Queue subscriptions remain discoverable. The host derives
+Queue subscriptions from normalized `experimentalTriggers`; direct Schedules
+resolve the same registry by output identity and use Schedule CloudEvents.
+`matchedFunctionPatterns` lists authored function keys resolved by the provider
+so the host can aggregate unmatched diagnostics across owners.
+
+Use existing deployment normalization for output paths and
+`getLambdaOptionsFromFunction` for source-backed trigger metadata. Queue consumer
+identity comes from the matched configuration pattern, not the output path.
+
+## Generic fallback
+
+Conventional per-entrypoint builders need no custom hook. The host can use its
+known source/output mapping, with the same zero-config versus explicit-build
+identity rules as deployment. A v3 result has one function artifact, but that
+does not guarantee a source-equals-public-URL mapping. Middleware, framework
+sentinels, and unknown multi-output modes must not be guessed. Variable-version
+builders need a known per-entrypoint convention or resolved output metadata.
+
+The optional hook is available to v2, v3, and variable-version builders. When
+present it is authoritative, including an empty manifest; no fallback runs.
+Absence means the host may use its supported conventional mapping.
+
+## Native schedules
+
+`schedules` optionally contains framework-native definitions in the static BOA
+`Schedule` shape. These refer to function output identities or Queue topics.
+They are metadata, not a request for a provider-owned timer. Nitro Tasks can use
+a direct Schedule function target without becoming Queue callbacks. Hosting and
+executing these definitions requires the separate Schedules integration.
+
+## Snapshot lifecycle
+
+- Retain provider scopes before filtering framework builders for native dev commands.
+- Discovery does not require the runtime to be listening. Invocation waits for
+  the owning runtime's readiness and follows its current process after restart.
+- Providers must not start another application server, scheduler, poller, or broker.
+- Cache until source/config/environment inputs change; providers must not retain
+  stale process-global discovery caches.
+- Validate the complete candidate set and discard superseded async results.
+  Errors retain the last valid snapshot.
+- Empty snapshots remove only that owner's registrations. Updates/removals must
+  preserve existing acknowledgments and active leases in delivery state.
+- Live runtime-generated updates need an authoritative refresh signal; source
+  watching alone does not promise discovery of virtual or ignored manifests.

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import FileFsRef from './file-fs-ref';
 import FileRef from './file-ref';
 import { Lambda, createLambda, getLambdaOptionsFromFunction, sanitizeConsumerName } from './lambda';
 import { NodejsLambda, type NodejsLambdaOptions } from './nodejs-lambda';
-import { Prerender, type PrerenderInitialMetadata } from './prerender';
+import { Prerender, type PrerenderInitialMetadata, type PrerenderOnMiss } from './prerender';
 import download, { downloadFile, type DownloadedFiles, isSymbolicLink, isDirectory, isExternalSymlink, isExternalSymlinkTarget, getSymlinkTarget } from './fs/download';
 import getWriteableDirectory from './fs/get-writable-directory';
 import glob, { type GlobOptions } from './fs/glob';
@@ -22,7 +22,7 @@ import { cloneEnv } from './clone-env';
 import { hardLinkDir } from './hard-link-dir';
 import { getNodeExecPath } from './get-node-exec-path';
 import { validateNpmrc } from './validate-npmrc';
-export type { NodejsLambdaOptions, PrerenderInitialMetadata };
+export type { NodejsLambdaOptions, PrerenderInitialMetadata, PrerenderOnMiss };
 export type { LambdaAffinity } from './lambda';
 export { FileBlob, FileFsRef, FileRef, Lambda, NodejsLambda, createLambda, Prerender, download, downloadFile, type DownloadedFiles, getWriteableDirectory, glob, type GlobOptions, rename, spawnAsync, getScriptName, installDependencies, runPackageJsonScript, execCommand, spawnCommand, walkParentDirs, getNodeBinPath, getNodeBinPaths, getNodeExecPath, getSupportedNodeVersion, isBunVersion, getSupportedBunVersion, getOrCreateBunBinary, detectPackageManager, runNpmInstall, type NpmInstallOutput, runBundleInstall, runPipInstall, type PipInstallResult, runShellScript, runCustomInstallCommand, resetCustomInstallCommandSet, getEnvForPackageManager, getNodeVersion, getPathForPackageManager, getLatestNodeVersion, getDiscontinuedNodeVersions, getSpawnOptions, getPlatformEnv, getPrefixedEnvVars, getServiceUrlEnvVars, getExperimentalServiceUrlEnvVars, streamToBuffer, streamToBufferChunks, debug, isSymbolicLink, isDirectory, isExternalSymlink, isExternalSymlinkTarget, getSymlinkTarget, getLambdaOptionsFromFunction, sanitizeConsumerName, scanParentDirs, findPackageJson, getIgnoreFilter, cloneEnv, hardLinkDir, traverseUpDirectories, validateNpmrc, type CliType, };
 export { EdgeFunction } from './edge-function';
@@ -50,6 +50,7 @@ export { getRegExpFromMatchers, resolveMiddlewareMatcher, } from './middleware-m
 export { BACKEND_FRAMEWORKS, BACKEND_BUILDERS, UNIFIED_BACKEND_BUILDER, type BackendFramework, isBackendFramework, isNodeBackendFramework, isBackendBuilder, isExperimentalBackendsEnabled, isExperimentalBackendsWithoutIntrospectionEnabled, shouldUseExperimentalBackends, PYTHON_FRAMEWORKS, type PythonFramework, isPythonFramework, } from './framework-helpers';
 export { isNodeEntrypoint } from './node-entrypoint';
 export * from './service-path-utils';
+export * from './schedule-path-utils';
 export { getEncryptedEnv, type EncryptedEnvFile, } from './process-serverless/get-encrypted-env-file';
 export { getLambdaEnvironment } from './process-serverless/get-lambda-environment';
 export { getLambdaPreloadScripts, type BytecodeCachingOptions, } from './process-serverless/get-lambda-preload-scripts';