@vercel/build-utils 13.23.0 → 13.25.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @vercel/build-utils
 
+## 13.25.0
+
+### Minor Changes
+
+- fb0cb8d: Add normalized entrypoint detector for runtime builders.
+- 4fc110b: [services] add preDeployCommand for experimentalServices
+
+## 13.24.0
+
+### Minor Changes
+
+- d874af6: Add support for env vars injection that reference other services in `services` with an explicit `env` configuration.
+
 ## 13.23.0
 
 ### Minor Changes

package/dist/get-service-url-env-vars.d.ts

@@ -1,4 +1,4 @@
-import type { Service } from './types';
+import type { EnvVars, Service } from './types';
 type Envs = {
     [key: string]: string | undefined;
 };
@@ -7,27 +7,49 @@ interface FrameworkInfo {
     envPrefix?: string;
 }
 export interface GetServiceUrlEnvVarsOptions {
+    requestedEnv: EnvVars;
+    consumerService?: Service;
+    services: Service[];
+    frameworkList: readonly FrameworkInfo[];
+    currentEnv?: Envs;
+    deploymentUrl?: string;
+    origin?: string;
+}
+export interface GetExperimentalServiceUrlEnvVarsOptions {
     services: Service[];
     frameworkList: readonly FrameworkInfo[];
     currentEnv?: Envs;
     deploymentUrl?: string;
     origin?: string;
-    envPrefix?: string;
 }
 /**
- * Generate environment variables for service URLs.
+ * Resolve a map of declared env-var refs into concrete URL values.
  *
- * For each web service, generates:
- * 1. A base env var with the full absolute URL (e.g., BACKEND_URL=https://deploy.vercel.app/api)
- *    for server-side use.
- * 2. Framework-prefixed versions with only the route prefix path
- *    (e.g., NEXT_PUBLIC_BACKEND_URL=/api, VITE_BACKEND_URL=/api) for client-side use.
- *    Using relative paths avoids CORS issues since the browser resolves them against
- *    the current origin, which works correctly across production domains, preview
- *    deployments, and custom domains.
+ * By default the value is the absolute URL of the referenced web service,
+ * while if a consumer's framework has an `envPrefix`
+ * (e.g. `NEXT_PUBLIC_` or `VITE_`) and the declared name starts with that prefix
+ * then the target's route prefix (e.g. `/api`) is used,
+ * which useful for client bundles where same-origin requests avoid CORS.
  *
  * Environment variables that are already set in `currentEnv` will NOT be overwritten,
  * allowing user-defined values to take precedence.
  */
 export declare function getServiceUrlEnvVars(options: GetServiceUrlEnvVarsOptions): Record<string, string>;
+/**
+ * Legacy implicit URL injection used for `experimentalServices` (and
+ * auto-detected services that map to the experimentalServices shape).
+ *
+ * For each web service, generates:
+ * 1. `{NAME}_URL` with the absolute URL (server-side use).
+ * 2. `{PREFIX}{NAME}_URL` for every framework prefix in `frameworkList` that
+ *    matches a service in the deployment, with the relative route prefix
+ *    (client-side use; relative paths avoid CORS).
+ *
+ * Entries already present in `currentEnv` are not overwritten — user-defined
+ * values win.
+ *
+ * The GA `services` field replaces this with explicit `env` declarations
+ * handled by `getServiceUrlEnvVars`.
+ */
+export declare function getExperimentalServiceUrlEnvVars(options: GetExperimentalServiceUrlEnvVarsOptions): Record<string, string>;
 export {};

package/dist/get-service-url-env-vars.js

@@ -18,6 +18,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var get_service_url_env_vars_exports = {};
 __export(get_service_url_env_vars_exports, {
+  getExperimentalServiceUrlEnvVars: () => getExperimentalServiceUrlEnvVars,
   getServiceUrlEnvVars: () => getServiceUrlEnvVars
 });
 module.exports = __toCommonJS(get_service_url_env_vars_exports);
@@ -44,12 +45,46 @@ function getFrameworkEnvPrefix(frameworkSlug, frameworkList) {
 }
 function getServiceUrlEnvVars(options) {
   const {
+    requestedEnv,
+    consumerService,
     services,
     frameworkList,
     currentEnv = {},
     deploymentUrl,
-    origin,
-    envPrefix
+    origin
+  } = options;
+  const baseUrl = origin || deploymentUrl;
+  if (!baseUrl)
+    return {};
+  const servicesByName = new Map(services.map((s) => [s.name, s]));
+  const consumerEnvPrefix = getFrameworkEnvPrefix(
+    consumerService?.framework,
+    frameworkList
+  );
+  const result = {};
+  for (const [name, envVar] of Object.entries(requestedEnv)) {
+    if (name in currentEnv) {
+      continue;
+    }
+    if (envVar.type !== "service-ref") {
+      continue;
+    }
+    const target = servicesByName.get(envVar.service);
+    if (!target || target.type !== "web" || !target.routePrefix) {
+      continue;
+    }
+    const isClientSide = !!consumerEnvPrefix && name.startsWith(consumerEnvPrefix) && name.length > consumerEnvPrefix.length;
+    result[name] = isClientSide ? target.routePrefix : computeServiceUrl(baseUrl, target.routePrefix, !!origin);
+  }
+  return result;
+}
+function getExperimentalServiceUrlEnvVars(options) {
+  const {
+    services,
+    frameworkList,
+    currentEnv = {},
+    deploymentUrl,
+    origin
   } = options;
   const baseUrl = origin || deploymentUrl;
   if (!baseUrl || !services || services.length === 0) {
@@ -73,12 +108,11 @@ function getServiceUrlEnvVars(options) {
       service.routePrefix,
       !!origin
     );
-    const effectiveBaseEnvVarName = envPrefix ? `${envPrefix}${baseEnvVarName}` : baseEnvVarName;
-    if (!(effectiveBaseEnvVarName in currentEnv)) {
-      envVars[effectiveBaseEnvVarName] = absoluteUrl;
+    if (!(baseEnvVarName in currentEnv)) {
+      envVars[baseEnvVarName] = absoluteUrl;
     }
     for (const prefix of frameworkPrefixes) {
-      const prefixedEnvVarName = envPrefix ? `${prefix}${envPrefix}${baseEnvVarName}` : `${prefix}${baseEnvVarName}`;
+      const prefixedEnvVarName = `${prefix}${baseEnvVarName}`;
       if (!(prefixedEnvVarName in currentEnv)) {
         envVars[prefixedEnvVarName] = service.routePrefix;
       }
@@ -88,5 +122,6 @@ function getServiceUrlEnvVars(options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  getExperimentalServiceUrlEnvVars,
   getServiceUrlEnvVars
 });

package/dist/index.d.ts

@@ -15,12 +15,12 @@ import debug from './debug';
 import getIgnoreFilter from './get-ignore-filter';
 import { getPlatformEnv } from './get-platform-env';
 import { getPrefixedEnvVars } from './get-prefixed-env-vars';
-import { getServiceUrlEnvVars } from './get-service-url-env-vars';
+import { getServiceUrlEnvVars, getExperimentalServiceUrlEnvVars } from './get-service-url-env-vars';
 import { cloneEnv } from './clone-env';
 import { hardLinkDir } from './hard-link-dir';
 import { validateNpmrc } from './validate-npmrc';
 export type { NodejsLambdaOptions };
-export { FileBlob, FileFsRef, FileRef, Lambda, NodejsLambda, createLambda, Prerender, download, downloadFile, DownloadedFiles, getWriteableDirectory, glob, GlobOptions, rename, spawnAsync, getScriptName, installDependencies, runPackageJsonScript, execCommand, spawnCommand, walkParentDirs, getNodeBinPath, getNodeBinPaths, getSupportedNodeVersion, isBunVersion, getSupportedBunVersion, detectPackageManager, runNpmInstall, NpmInstallOutput, runBundleInstall, runPipInstall, PipInstallResult, runShellScript, runCustomInstallCommand, resetCustomInstallCommandSet, getEnvForPackageManager, getNodeVersion, getPathForPackageManager, getLatestNodeVersion, getDiscontinuedNodeVersions, getSpawnOptions, getPlatformEnv, getPrefixedEnvVars, getServiceUrlEnvVars, streamToBuffer, streamToBufferChunks, debug, isSymbolicLink, isDirectory, getLambdaOptionsFromFunction, sanitizeConsumerName, scanParentDirs, findPackageJson, getIgnoreFilter, cloneEnv, hardLinkDir, traverseUpDirectories, validateNpmrc, };
+export { FileBlob, FileFsRef, FileRef, Lambda, NodejsLambda, createLambda, Prerender, download, downloadFile, DownloadedFiles, getWriteableDirectory, glob, GlobOptions, rename, spawnAsync, getScriptName, installDependencies, runPackageJsonScript, execCommand, spawnCommand, walkParentDirs, getNodeBinPath, getNodeBinPaths, getSupportedNodeVersion, isBunVersion, getSupportedBunVersion, detectPackageManager, runNpmInstall, NpmInstallOutput, runBundleInstall, runPipInstall, PipInstallResult, runShellScript, runCustomInstallCommand, resetCustomInstallCommandSet, getEnvForPackageManager, getNodeVersion, getPathForPackageManager, getLatestNodeVersion, getDiscontinuedNodeVersions, getSpawnOptions, getPlatformEnv, getPrefixedEnvVars, getServiceUrlEnvVars, getExperimentalServiceUrlEnvVars, streamToBuffer, streamToBufferChunks, debug, isSymbolicLink, isDirectory, getLambdaOptionsFromFunction, sanitizeConsumerName, scanParentDirs, findPackageJson, getIgnoreFilter, cloneEnv, hardLinkDir, traverseUpDirectories, validateNpmrc, };
 export { EdgeFunction } from './edge-function';
 export { readConfigFile, getPackageJson } from './fs/read-config-file';
 export { normalizePath } from './fs/normalize-path';

package/dist/index.js

@@ -34489,6 +34489,7 @@ __export(src_exports, {
   BACKEND_FRAMEWORKS: () => BACKEND_FRAMEWORKS,
   BUILDER_COMPILE_STEP: () => BUILDER_COMPILE_STEP,
   BUILDER_INSTALLER_STEP: () => BUILDER_INSTALLER_STEP,
+  BUILDER_PRE_DEPLOY_STEP: () => BUILDER_PRE_DEPLOY_STEP,
   BunVersion: () => BunVersion,
   ENV_WRAPPER_SUPPORTED_FAMILIES: () => ENV_WRAPPER_SUPPORTED_FAMILIES,
   EdgeFunction: () => EdgeFunction,
@@ -34539,6 +34540,7 @@ __export(src_exports, {
   getDiscontinuedNodeVersions: () => getDiscontinuedNodeVersions,
   getEncryptedEnv: () => getEncryptedEnv,
   getEnvForPackageManager: () => getEnvForPackageManager,
+  getExperimentalServiceUrlEnvVars: () => getExperimentalServiceUrlEnvVars,
   getIgnoreFilter: () => get_ignore_filter_default,
   getInstalledPackageVersion: () => getInstalledPackageVersion,
   getInternalServiceCronPath: () => getInternalServiceCronPath,
@@ -37949,12 +37951,46 @@ function getFrameworkEnvPrefix(frameworkSlug, frameworkList) {
 }
 function getServiceUrlEnvVars(options) {
   const {
+    requestedEnv,
+    consumerService,
     services,
     frameworkList,
     currentEnv = {},
     deploymentUrl,
-    origin,
-    envPrefix
+    origin
+  } = options;
+  const baseUrl = origin || deploymentUrl;
+  if (!baseUrl)
+    return {};
+  const servicesByName = new Map(services.map((s) => [s.name, s]));
+  const consumerEnvPrefix = getFrameworkEnvPrefix(
+    consumerService?.framework,
+    frameworkList
+  );
+  const result = {};
+  for (const [name, envVar] of Object.entries(requestedEnv)) {
+    if (name in currentEnv) {
+      continue;
+    }
+    if (envVar.type !== "service-ref") {
+      continue;
+    }
+    const target = servicesByName.get(envVar.service);
+    if (!target || target.type !== "web" || !target.routePrefix) {
+      continue;
+    }
+    const isClientSide = !!consumerEnvPrefix && name.startsWith(consumerEnvPrefix) && name.length > consumerEnvPrefix.length;
+    result[name] = isClientSide ? target.routePrefix : computeServiceUrl(baseUrl, target.routePrefix, !!origin);
+  }
+  return result;
+}
+function getExperimentalServiceUrlEnvVars(options) {
+  const {
+    services,
+    frameworkList,
+    currentEnv = {},
+    deploymentUrl,
+    origin
   } = options;
   const baseUrl = origin || deploymentUrl;
   if (!baseUrl || !services || services.length === 0) {
@@ -37978,12 +38014,11 @@ function getServiceUrlEnvVars(options) {
       service.routePrefix,
       !!origin
     );
-    const effectiveBaseEnvVarName = envPrefix ? `${envPrefix}${baseEnvVarName}` : baseEnvVarName;
-    if (!(effectiveBaseEnvVarName in currentEnv)) {
-      envVars[effectiveBaseEnvVarName] = absoluteUrl;
+    if (!(baseEnvVarName in currentEnv)) {
+      envVars[baseEnvVarName] = absoluteUrl;
     }
     for (const prefix of frameworkPrefixes) {
-      const prefixedEnvVarName = envPrefix ? `${prefix}${envPrefix}${baseEnvVarName}` : `${prefix}${baseEnvVarName}`;
+      const prefixedEnvVarName = `${prefix}${baseEnvVarName}`;
       if (!(prefixedEnvVarName in currentEnv)) {
         envVars[prefixedEnvVarName] = service.routePrefix;
       }
@@ -38910,6 +38945,7 @@ var Span = class _Span {
 // src/trace/constants.ts
 var BUILDER_INSTALLER_STEP = "vc.builder.install";
 var BUILDER_COMPILE_STEP = "vc.builder.build";
+var BUILDER_PRE_DEPLOY_STEP = "vc.builder.preDeploy";
 
 // src/get-installed-package-version.ts
 async function getInstalledPackageVersion(packageName, path8) {
@@ -40248,6 +40284,7 @@ function getExtendedPayload({
   BACKEND_FRAMEWORKS,
   BUILDER_COMPILE_STEP,
   BUILDER_INSTALLER_STEP,
+  BUILDER_PRE_DEPLOY_STEP,
   BunVersion,
   ENV_WRAPPER_SUPPORTED_FAMILIES,
   EdgeFunction,
@@ -40298,6 +40335,7 @@ function getExtendedPayload({
   getDiscontinuedNodeVersions,
   getEncryptedEnv,
   getEnvForPackageManager,
+  getExperimentalServiceUrlEnvVars,
   getIgnoreFilter,
   getInstalledPackageVersion,
   getInternalServiceCronPath,

package/dist/trace/constants.d.ts

@@ -1,2 +1,3 @@
 export declare const BUILDER_INSTALLER_STEP = "vc.builder.install";
 export declare const BUILDER_COMPILE_STEP = "vc.builder.build";
+export declare const BUILDER_PRE_DEPLOY_STEP = "vc.builder.preDeploy";

package/dist/trace/constants.js

@@ -19,13 +19,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var constants_exports = {};
 __export(constants_exports, {
   BUILDER_COMPILE_STEP: () => BUILDER_COMPILE_STEP,
-  BUILDER_INSTALLER_STEP: () => BUILDER_INSTALLER_STEP
+  BUILDER_INSTALLER_STEP: () => BUILDER_INSTALLER_STEP,
+  BUILDER_PRE_DEPLOY_STEP: () => BUILDER_PRE_DEPLOY_STEP
 });
 module.exports = __toCommonJS(constants_exports);
 const BUILDER_INSTALLER_STEP = "vc.builder.install";
 const BUILDER_COMPILE_STEP = "vc.builder.build";
+const BUILDER_PRE_DEPLOY_STEP = "vc.builder.preDeploy";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BUILDER_COMPILE_STEP,
-  BUILDER_INSTALLER_STEP
+  BUILDER_INSTALLER_STEP,
+  BUILDER_PRE_DEPLOY_STEP
 });

package/dist/trace/index.d.ts

@@ -1,3 +1,3 @@
 export { Span } from './trace';
-export { BUILDER_COMPILE_STEP, BUILDER_INSTALLER_STEP } from './constants';
+export { BUILDER_COMPILE_STEP, BUILDER_INSTALLER_STEP, BUILDER_PRE_DEPLOY_STEP, } from './constants';
 export type { SpanId, TraceEvent, Reporter } from './trace';

package/dist/trace/index.js

@@ -20,6 +20,7 @@ var trace_exports = {};
 __export(trace_exports, {
   BUILDER_COMPILE_STEP: () => import_constants.BUILDER_COMPILE_STEP,
   BUILDER_INSTALLER_STEP: () => import_constants.BUILDER_INSTALLER_STEP,
+  BUILDER_PRE_DEPLOY_STEP: () => import_constants.BUILDER_PRE_DEPLOY_STEP,
   Span: () => import_trace.Span
 });
 module.exports = __toCommonJS(trace_exports);
@@ -29,5 +30,6 @@ var import_constants = require("./constants");
 0 && (module.exports = {
   BUILDER_COMPILE_STEP,
   BUILDER_INSTALLER_STEP,
+  BUILDER_PRE_DEPLOY_STEP,
   Span
 });

package/dist/types.d.ts

@@ -97,6 +97,12 @@ export interface BuildOptions {
      * fully processed
      */
     buildCallback?: (opts: Omit<BuildOptions, 'buildCallback'>) => Promise<void>;
+    /**
+     * Called by the builder to register a callback that will execute the
+     * service's pre-deploy command. The CLI collects these and invokes
+     * them only after every builder has succeeded.
+     */
+    registerPreDeploy?: (callback: () => Promise<void>) => void;
     /**
      * The current trace state from the internal vc tracing
      */
@@ -500,6 +506,12 @@ export interface ServiceQueueTopic {
 export type ServiceTopics = string[] | ServiceQueueTopic[];
 export declare const JOB_TRIGGERS: readonly ["queue", "schedule", "workflow"];
 export type JobTrigger = (typeof JOB_TRIGGERS)[number];
+export interface ServiceRefEnvVar {
+    type: 'service-ref';
+    service: string;
+}
+export type EnvVar = ServiceRefEnvVar;
+export type EnvVars = Record<string, EnvVar>;
 export interface Service {
     name: string;
     type: ServiceType;
@@ -512,14 +524,14 @@ export interface Service {
     runtime?: string;
     buildCommand?: string;
     installCommand?: string;
+    preDeployCommand?: string;
     routePrefix?: string;
     routePrefixSource?: 'configured' | 'generated';
     subdomain?: string;
     schedule?: string | string[];
     handlerFunction?: string;
     topics?: ServiceTopics;
-    /** custom prefix to inject service URL env vars */
-    envPrefix?: string;
+    env?: EnvVars;
 }
 export declare function getServiceQueueTopicConfigs(config: {
     type?: ServiceType;
@@ -744,8 +756,7 @@ export interface ExperimentalServiceConfig {
     /** Cron schedule expression(s) (e.g., "0 0 * * *") */
     schedule?: string | string[];
     topics?: ServiceTopics;
-    /** Custom prefix to use to inject service URL env vars */
-    envPrefix?: string;
+    env?: EnvVars;
 }
 /**
  * Map of service name to service configuration.
@@ -801,3 +812,37 @@ export type Services = Record<string, ServiceConfig>;
  * }
  */
 export type ExperimentalServiceGroups = Record<string, string[]>;
+/**
+ * Result of a runtime builder's normalized entrypoint detection.
+ *
+ * - `kind: 'file'` — `entrypoint` is a path relative to the scanned `workPath`
+ *   (e.g. `"src/index.ts"`, `"main.go"`, `"main.py"`).
+ * - `kind: 'py-module:attr'` — `entrypoint` is a Python `module:attr` reference
+ *   where the module is dot-separated and resolved relative to the scanned
+ *   `workPath` (e.g. `"main:app"`, `"src.main:app"`).
+ *
+ * @experimental This feature is experimental and may change.
+ */
+export type DetectedEntrypoint = {
+    kind: 'file';
+    entrypoint: string;
+} | {
+    kind: 'py-module:attr';
+    entrypoint: string;
+} | null;
+/**
+ * Input to a runtime builder's normalized entrypoint detector.
+ * @experimental This feature is experimental and may change.
+ */
+export interface DetectEntrypointOptions {
+    /** Path to the candidate service directory relative to project root. */
+    workPath: string;
+    /** Framework slug detected for this directory, if any. */
+    framework?: string;
+}
+/**
+ * Normalized entrypoint detector signature, implemented by each runtime builder
+ * and consumed by services auto-detection to populate suggested service configs.
+ * @experimental This feature is experimental and may change.
+ */
+export type DetectEntrypointFn = (opts: DetectEntrypointOptions) => Promise<DetectedEntrypoint>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/build-utils",
-  "version": "13.23.0",
+  "version": "13.25.0",
   "license": "Apache-2.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.js",