@vercel/fs-detectors 6.2.1 → 6.3.0

package/dist/detect-builders.d.ts

@@ -1,5 +1,5 @@
 import type { Route } from '@vercel/routing-utils';
-import type { PackageJson, Builder, BuilderFunctions, ExperimentalServices, ProjectSettings, Service } from '@vercel/build-utils';
+import type { PackageJson, Builder, BuilderFunctions, Services, ExperimentalServices, ProjectSettings, Service } from '@vercel/build-utils';
 /**
  * Pattern for finding all supported middleware files.
  */
@@ -22,6 +22,7 @@ export interface ErrorResponse {
 export interface Options {
     tag?: string;
     functions?: BuilderFunctions;
+    services?: Services;
     experimentalServices?: ExperimentalServices;
     ignoreBuildScript?: boolean;
     projectSettings?: ProjectSettings;
@@ -46,4 +47,5 @@ export declare function detectBuilders(files: string[], pkg?: PackageJson | unde
     rewriteRoutes: Route[] | null;
     errorRoutes: Route[] | null;
     services?: Service[];
+    useImplicitEnvInjection?: boolean;
 }>;

package/dist/detect-builders.js

@@ -92,13 +92,14 @@ function detectOutputDirectory(builders) {
   return publicBuilder ? publicBuilder.src.replace("/**/*", "") : null;
 }
 async function detectBuilders(files, pkg, options = {}) {
-  const { experimentalServices: services, projectSettings = {} } = options;
+  const { services, experimentalServices, projectSettings = {} } = options;
   const { framework } = projectSettings;
-  const hasServicesConfig = services != null && typeof services === "object";
+  const configuredServices = services ?? experimentalServices;
+  const hasServicesConfig = configuredServices != null && typeof configuredServices === "object";
   if (hasServicesConfig || framework === "services") {
     return (0, import_get_services_builders.getServicesBuilders)({
       workPath: options.workPath,
-      configuredServices: services,
+      configuredServices,
       projectFramework: framework
     });
   }

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { autoDetectServices } from './services/auto-detect';
 export type { AutoDetectOptions, AutoDetectResult, } from './services/auto-detect';
 export { isStaticBuild, isRouteOwningBuilder, INTERNAL_SERVICE_PREFIX, getInternalServiceFunctionPath, getInternalServiceCronPath, getInternalServiceCronPathPrefix, getInternalServiceWorkerPath, getInternalServiceWorkerPathPrefix, } from './services/utils';
 export { getServicesBuilders } from './services/get-services-builders';
-export type { DetectServicesOptions, DetectServicesResult, DetectServicesSource, ServicesConfig, ResolvedServicesResult, InferredServicesResult, ResolvedService, Service, ServicesRoutes, ServiceDetectionError, } from './services/types';
+export type { DetectServicesOptions, DetectServicesResult, DetectServicesSource, InferredServicesConfig, ResolvedServicesResult, InferredServicesResult, ResolvedService, Service, ServicesRoutes, ServiceDetectionError, } from './services/types';
 export { detectFileSystemAPI } from './detect-file-system-api';
 export { detectFramework, detectFrameworks, detectFrameworkRecord, detectFrameworkVersion, } from './detect-framework';
 export { getProjectPaths } from './get-project-paths';

package/dist/services/auto-detect.d.ts

@@ -8,7 +8,7 @@ export interface AutoDetectResult {
     errors: ServiceDetectionError[];
 }
 /**
- * Auto-detect services when experimentalServices is not configured.
+ * Auto-detect services when services are not configured.
  *
  * Scans the project for frameworks, supporting multiple layouts:
  *

package/dist/services/auto-detect.js

@@ -44,7 +44,7 @@ async function autoDetectServices(options) {
       errors: [
         {
           code: "MULTIPLE_FRAMEWORKS_ROOT",
-          message: `Multiple frameworks detected at root: ${frameworkNames}. Use explicit experimentalServices config.`
+          message: `Multiple frameworks detected at root: ${frameworkNames}. Use explicit services config.`
         }
       ]
     };
@@ -69,7 +69,7 @@ async function autoDetectServices(options) {
         errors: [
           {
             code: "MULTIPLE_FRAMEWORKS_SERVICE",
-            message: `Multiple frameworks detected in ${frontendLocation}/: ${frameworkNames}. Use explicit experimentalServices config.`
+            message: `Multiple frameworks detected in ${frontendLocation}/: ${frameworkNames}. Use explicit services config.`
           }
         ]
       };
@@ -87,7 +87,7 @@ async function autoDetectServices(options) {
     errors: [
       {
         code: "NO_SERVICES_CONFIGURED",
-        message: "No services detected. Configure experimentalServices in vercel.json or ensure a framework exists at project root, frontend/, or apps/web/."
+        message: "No services detected. Configure services in vercel.json or ensure a framework exists at project root, frontend/, or apps/web/."
       }
     ]
   };
@@ -168,7 +168,7 @@ async function detectBackendServices(fs) {
         services: {},
         error: {
           code: "SERVICE_NAME_CONFLICT",
-          message: `Service name conflict: "${serviceName}" exists in both ${BACKEND_DIR}/ and ${SERVICES_DIR}/${serviceName}/. Rename one of the directories or use explicit experimentalServices config.`,
+          message: `Service name conflict: "${serviceName}" exists in both ${BACKEND_DIR}/ and ${SERVICES_DIR}/${serviceName}/. Rename one of the directories or use explicit services config.`,
           serviceName
         }
       };
@@ -217,7 +217,7 @@ async function detectServiceInDir(fs, dirPath, serviceName) {
     return {
       error: {
         code: "MULTIPLE_FRAMEWORKS_SERVICE",
-        message: `Multiple frameworks detected in ${dirPath}/: ${frameworkNames}. Use explicit experimentalServices config.`,
+        message: `Multiple frameworks detected in ${dirPath}/: ${frameworkNames}. Use explicit services config.`,
         serviceName
       }
     };

package/dist/services/detect-railway.js

@@ -109,7 +109,7 @@ async function detectRailwayServices(options) {
     if (frameworks.length === 0) {
       warnings.push({
         code: "SERVICE_SKIPPED",
-        message: `Skipped service in ${dirLabel}/: no framework detected. Configure it manually in experimentalServices.`
+        message: `Skipped service in ${dirLabel}/: no framework detected. Configure it manually in services.`
       });
       continue;
     }
@@ -117,7 +117,7 @@ async function detectRailwayServices(options) {
       const names = frameworks.map((f) => f.name).join(", ");
       errors.push({
         code: "MULTIPLE_FRAMEWORKS_SERVICE",
-        message: `Multiple frameworks detected in ${dirLabel}/: ${names}. Use explicit experimentalServices config.`,
+        message: `Multiple frameworks detected in ${dirLabel}/: ${names}. Use explicit services config.`,
         serviceName
       });
       continue;

package/dist/services/detect-services.d.ts

@@ -2,7 +2,7 @@ import { type DetectServicesOptions, type DetectServicesResult, type Service, ty
 /**
  * Detect and resolve services within a project.
  *
- * Reads vercel.json and resolves `experimentalServices` into Service objects.
+ * Reads vercel.json and resolves configured services into Service objects.
  * Returns an error if no services are configured.
  */
 export declare function detectServices(options: DetectServicesOptions): Promise<DetectServicesResult>;

package/dist/services/detect-services.js

@@ -42,10 +42,17 @@ function emptyRoutes() {
     workers: []
   };
 }
+function isEnvVars(env) {
+  if (!env)
+    return false;
+  const first = Object.values(env)[0];
+  return typeof first === "object" && first !== null;
+}
 function withResolvedResult(resolved, inferred = null) {
   return {
     services: resolved.services,
     source: resolved.source,
+    useImplicitEnvInjection: resolved.useImplicitEnvInjection,
     routes: resolved.routes,
     errors: resolved.errors,
     warnings: resolved.warnings,
@@ -81,12 +88,14 @@ async function detectServices(options) {
     return withResolvedResult({
       services: [],
       source: "configured",
+      useImplicitEnvInjection: true,
       routes: emptyRoutes(),
       errors: [configError],
       warnings: []
     });
   }
-  const configuredServices = vercelConfig?.experimentalServices;
+  const hasNonEmptyPublicServicesConfig = vercelConfig?.services && Object.keys(vercelConfig.services).length > 0;
+  const configuredServices = hasNonEmptyPublicServicesConfig ? vercelConfig.services : vercelConfig?.experimentalServices;
   const hasConfiguredServices = configuredServices && Object.keys(configuredServices).length > 0;
   if (!hasConfiguredServices) {
     const railwayResult = await (0, import_detect_railway.detectRailwayServices)({ fs: scopedFs });
@@ -94,6 +103,7 @@ async function detectServices(options) {
       return withResolvedResult({
         services: [],
         source: "auto-detected",
+        useImplicitEnvInjection: true,
         routes: emptyRoutes(),
         errors: railwayResult.errors,
         warnings: railwayResult.warnings
@@ -115,6 +125,7 @@ async function detectServices(options) {
         {
           services: [],
           source: "auto-detected",
+          useImplicitEnvInjection: true,
           routes: emptyRoutes(),
           errors: result2.errors,
           warnings: railwayResult.warnings
@@ -133,6 +144,7 @@ async function detectServices(options) {
       const resolved = {
         services: result2.services,
         source: "auto-detected",
+        useImplicitEnvInjection: true,
         routes: routes2,
         errors: result2.errors,
         warnings: []
@@ -151,6 +163,7 @@ async function detectServices(options) {
       return withResolvedResult({
         services: [],
         source: "auto-detected",
+        useImplicitEnvInjection: true,
         routes: emptyRoutes(),
         errors: autoResult.errors,
         warnings: []
@@ -159,11 +172,12 @@ async function detectServices(options) {
     return withResolvedResult({
       services: [],
       source: "auto-detected",
+      useImplicitEnvInjection: true,
       routes: emptyRoutes(),
       errors: [
         {
           code: "NO_SERVICES_CONFIGURED",
-          message: "No services configured. Add `experimentalServices` to vercel.json."
+          message: "No services configured. Add `services` to vercel.json."
         }
       ],
       warnings: []
@@ -172,12 +186,21 @@ async function detectServices(options) {
   const result = await (0, import_resolve.resolveAllConfiguredServices)(
     configuredServices,
     scopedFs,
-    "configured"
+    "configured",
+    {
+      requireFileEntrypointForBackendRuntimes: Boolean(
+        hasNonEmptyPublicServicesConfig
+      ),
+      rootEnv: isEnvVars(vercelConfig?.env) ? vercelConfig?.env : void 0
+    }
   );
   const routes = generateServicesRoutes(result.services);
   return withResolvedResult({
     services: result.services,
     source: "configured",
+    // GA `services` opts into explicit `env`; experimentalServices keeps
+    // the legacy `{NAME}_URL` injection.
+    useImplicitEnvInjection: !hasNonEmptyPublicServicesConfig,
     routes,
     errors: result.errors,
     warnings: []

package/dist/services/get-services-builders.d.ts

@@ -23,6 +23,7 @@ export interface ServicesBuildersResult {
     rewriteRoutes: Route[] | null;
     errorRoutes: Route[] | null;
     services?: ResolvedService[];
+    useImplicitEnvInjection?: boolean;
 }
 /**
  * Get builders for services - adapter for detectBuilders.

package/dist/services/get-services-builders.js

@@ -94,7 +94,7 @@ async function getServicesBuilders(options) {
       errors: [
         {
           code: "NO_SERVICES_CONFIGURED",
-          message: "No services configured. Add `experimentalServices` to vercel.json."
+          message: "No services configured. Add `services` to vercel.json."
         }
       ],
       warnings: warningResponses,
@@ -121,7 +121,8 @@ async function getServicesBuilders(options) {
       ...result.routes.crons
     ] : null,
     errorRoutes: [],
-    services: result.services
+    services: result.services,
+    useImplicitEnvInjection: result.useImplicitEnvInjection
   };
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/services/resolve.d.ts

@@ -1,5 +1,6 @@
-import type { Service, ExperimentalServiceConfig, ExperimentalServices, ServiceDetectionError } from './types';
+import type { EnvVars, Service, ConfiguredServices, ExperimentalServiceConfig, ServiceConfig, ServiceDetectionError } from './types';
 import type { DetectorFilesystem } from '../detectors/filesystem';
+type ConfiguredServiceConfig = (ServiceConfig | ExperimentalServiceConfig) & Partial<ExperimentalServiceConfig>;
 interface ResolvedEntrypointPath {
     normalized: string;
     isDirectory: boolean;
@@ -7,7 +8,7 @@ interface ResolvedEntrypointPath {
 type RoutePrefixSource = 'configured' | 'generated';
 interface ResolveConfiguredServiceOptions {
     name: string;
-    config: ExperimentalServiceConfig;
+    config: ConfiguredServiceConfig;
     /** Filesystem scoped to the service root (via chdir) when root is set, otherwise the project-level fs. */
     serviceFs: DetectorFilesystem;
     root?: string;
@@ -15,20 +16,29 @@ interface ResolveConfiguredServiceOptions {
     resolvedEntrypoint?: ResolvedEntrypointPath;
     routePrefixSource?: RoutePrefixSource;
 }
+interface ResolveAllConfiguredServicesOptions {
+    requireFileEntrypointForBackendRuntimes?: boolean;
+    /**
+     * Optional top-level `env` (from vercel.json `env`). Per-service `env`
+     * values take precedence; entries here are folded into every service that
+     * doesn't already define the same name.
+     */
+    rootEnv?: EnvVars;
+}
 /**
- * Validate a service configuration from vercel.json experimentalServices.
+ * Validate a service configuration from vercel.json services.
  */
-export declare function validateServiceConfig(name: string, config: ExperimentalServiceConfig): ServiceDetectionError | null;
-export declare function validateServiceEntrypoint(name: string, config: ExperimentalServiceConfig, resolvedEntrypoint: ResolvedEntrypointPath): ServiceDetectionError | null;
+export declare function validateServiceConfig(name: string, config: ConfiguredServiceConfig, options?: ResolveAllConfiguredServicesOptions): ServiceDetectionError | null;
+export declare function validateServiceEntrypoint(name: string, config: ConfiguredServiceConfig, resolvedEntrypoint: ResolvedEntrypointPath): ServiceDetectionError | null;
 /**
  * Resolve a single service from user configuration.
  */
 export declare function resolveConfiguredService(options: ResolveConfiguredServiceOptions): Promise<Service>;
 /**
- * Resolve all services from vercel.json experimentalServices.
+ * Resolve all services from vercel.json services.
  * Validates each service configuration.
  */
-export declare function resolveAllConfiguredServices(services: ExperimentalServices, fs: DetectorFilesystem, routePrefixSource?: RoutePrefixSource): Promise<{
+export declare function resolveAllConfiguredServices(services: ConfiguredServices, fs: DetectorFilesystem, routePrefixSource?: RoutePrefixSource, options?: ResolveAllConfiguredServicesOptions): Promise<{
     services: Service[];
     errors: ServiceDetectionError[];
 }>;

package/dist/services/resolve.js

@@ -45,7 +45,12 @@ function parsePyModuleAttrEntrypoint(entrypoint) {
 }
 const SERVICE_NAME_REGEX = /^[a-zA-Z]([a-zA-Z0-9_-]*[a-zA-Z0-9])?$/;
 const DNS_LABEL_RE = /^(?!-)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i;
-const ENV_PREFIX_RE = /^[A-Z][A-Z0-9_]*_$/;
+const ENV_VAR_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ENTRYPOINT_REQUIRED_RUNTIMES = /* @__PURE__ */ new Set([
+  "node",
+  "python",
+  "go"
+]);
 async function getServiceFs(fs, serviceName, root) {
   if (!root) {
     return { fs };
@@ -77,6 +82,38 @@ function normalizeServiceEntrypoint(entrypoint) {
   const normalized = import_path.posix.normalize(entrypoint);
   return normalized === "" ? "." : normalized;
 }
+function getEffectiveServiceTrigger(config) {
+  if (config.type === "cron") {
+    return "schedule";
+  }
+  if (config.type === "worker") {
+    return "queue";
+  }
+  if (config.type !== "job") {
+    return void 0;
+  }
+  return config.trigger;
+}
+function getEntrypointRequiredRuntime(config) {
+  if (config.runtime && config.runtime in import_types.RUNTIME_BUILDERS) {
+    return config.runtime;
+  }
+  return (0, import_utils.inferRuntimeFromFramework)(config.framework);
+}
+function validateBackendFileEntrypoint(name, config, resolvedEntrypoint, options) {
+  if (!options.requireFileEntrypointForBackendRuntimes || !resolvedEntrypoint?.isDirectory) {
+    return null;
+  }
+  const runtime = getEntrypointRequiredRuntime(config);
+  if (!runtime || !ENTRYPOINT_REQUIRED_RUNTIMES.has(runtime)) {
+    return null;
+  }
+  return {
+    code: "INVALID_ENTRYPOINT",
+    message: `Service "${name}" must specify a file "entrypoint" when using "${config.runtime ? "runtime" : "framework"}" "${config.runtime || config.framework}".`,
+    serviceName: name
+  };
+}
 async function resolveEntrypointPath({
   fs,
   serviceName,
@@ -171,7 +208,7 @@ async function detectFrameworkFromWorkspace({
     return {
       error: {
         code: "MULTIPLE_FRAMEWORKS_SERVICE",
-        message: `Multiple frameworks detected in ${workspace === "." ? "project root" : `${workspace}/`}: ${frameworkNames}. Specify "framework" explicitly in experimentalServices.`,
+        message: `Multiple frameworks detected in ${workspace === "." ? "project root" : `${workspace}/`}: ${frameworkNames}. Specify "framework" explicitly in services.`,
         serviceName
       }
     };
@@ -265,7 +302,7 @@ function resolveServiceRoutingConfig(name, config) {
     }
   };
 }
-function validateServiceConfig(name, config) {
+function validateServiceConfig(name, config, options = {}) {
   if (!SERVICE_NAME_REGEX.test(name)) {
     return {
       code: "INVALID_SERVICE_NAME",
@@ -281,13 +318,15 @@ function validateServiceConfig(name, config) {
     };
   }
   const serviceType = config.type || "web";
-  const isJobService = serviceType === "job" || serviceType === "cron";
-  const isScheduleJobService = (0, import_build_utils.isScheduleTriggeredService)({
+  const effectiveTrigger = getEffectiveServiceTrigger(config);
+  const effectiveService = {
     type: serviceType,
-    trigger: config.trigger
-  });
-  const isQueueJobService = serviceType === "job" && config.trigger === "queue";
-  const isWorkflowService = serviceType === "job" && config.trigger === "workflow";
+    trigger: effectiveTrigger
+  };
+  const isJobService = serviceType === "job" || serviceType === "cron";
+  const isScheduleJobService = (0, import_build_utils.isScheduleTriggeredService)(effectiveService);
+  const isQueueJobService = serviceType === "job" && (0, import_build_utils.isQueueTriggeredService)(effectiveService);
+  const isWorkflowService = serviceType === "job" && effectiveTrigger === "workflow";
   const isNonWebService = serviceType === "worker" || isJobService;
   const serviceTypeLabel = isJobService ? "Job" : serviceType === "worker" ? "Worker" : "Web";
   const routingResult = resolveServiceRoutingConfig(name, config);
@@ -333,17 +372,17 @@ function validateServiceConfig(name, config) {
       serviceName: name
     };
   }
-  if (serviceType === "job" && config.trigger === void 0) {
+  if (serviceType === "job" && effectiveTrigger === void 0) {
     return {
       code: "MISSING_JOB_TRIGGER",
       message: `Job service "${name}" is missing required "trigger" field.`,
       serviceName: name
     };
   }
-  if (serviceType === "job" && config.trigger && !import_build_utils.JOB_TRIGGERS.includes(config.trigger)) {
+  if (serviceType === "job" && effectiveTrigger && !import_build_utils.JOB_TRIGGERS.includes(effectiveTrigger)) {
     return {
       code: "INVALID_JOB_TRIGGER",
-      message: `Job service "${name}" has invalid trigger "${config.trigger}". Expected ${import_build_utils.JOB_TRIGGERS.map((t) => `"${t}"`).join(", ")}.`,
+      message: `Job service "${name}" has invalid trigger "${effectiveTrigger}". Expected ${import_build_utils.JOB_TRIGGERS.map((t) => `"${t}"`).join(", ")}.`,
       serviceName: name
     };
   }
@@ -385,14 +424,46 @@ function validateServiceConfig(name, config) {
       };
     }
   }
-  if (config.envPrefix !== void 0) {
-    if (!ENV_PREFIX_RE.test(config.envPrefix)) {
+  if (config.env !== void 0) {
+    if (typeof config.env !== "object" || Array.isArray(config.env)) {
       return {
-        code: "INVALID_ENV_PREFIX",
-        message: `Service "${name}" has invalid envPrefix "${config.envPrefix}". Must start with an uppercase letter, contain only uppercase letters, digits, and underscores, and end with "_" (e.g., "MY_SERVICE_").`,
+        code: "INVALID_ENV_VARS",
+        message: `Service "${name}" has invalid "env". Must be an object keyed by environment variable name.`,
         serviceName: name
       };
     }
+    for (const [envVarName, envVar] of Object.entries(config.env)) {
+      if (!ENV_VAR_NAME_RE.test(envVarName)) {
+        return {
+          code: "INVALID_ENV_VAR_NAME",
+          message: `Service "${name}" has invalid env key "${envVarName}". Must match /^[A-Za-z_][A-Za-z0-9_]*$/.`,
+          serviceName: name
+        };
+      }
+      if (!envVar || typeof envVar !== "object" || Array.isArray(envVar)) {
+        return {
+          code: "INVALID_ENV_VAR",
+          message: `Service "${name}" has invalid env["${envVarName}"]. Must be an object with a "type" discriminator.`,
+          serviceName: name
+        };
+      }
+      const envVarType = envVar.type;
+      if (envVarType !== "service-ref") {
+        return {
+          code: "INVALID_ENV_VAR_TYPE",
+          message: `Service "${name}" env["${envVarName}"] has unknown type "${envVarType}".`,
+          serviceName: name
+        };
+      }
+      const refService = envVar.service;
+      if (typeof refService !== "string" || refService.length === 0) {
+        return {
+          code: "INVALID_ENV_VAR_REF",
+          message: `Service "${name}" env["${envVarName}"] must specify "service" as a non-empty string.`,
+          serviceName: name
+        };
+      }
+    }
   }
   if (config.runtime && !(config.runtime in import_types.RUNTIME_BUILDERS)) {
     return {
@@ -421,6 +492,7 @@ function validateServiceConfig(name, config) {
   const hasFramework = Boolean(config.framework);
   const hasBuilderOrRuntime = Boolean(config.builder || config.runtime);
   const hasEntrypoint = Boolean(config.entrypoint);
+  const entrypointRequiredRuntime = getEntrypointRequiredRuntime(config);
   if (!hasFramework && !hasBuilderOrRuntime && !hasEntrypoint) {
     return {
       code: "MISSING_SERVICE_CONFIG",
@@ -428,6 +500,13 @@ function validateServiceConfig(name, config) {
       serviceName: name
     };
   }
+  if (options.requireFileEntrypointForBackendRuntimes && !hasEntrypoint && entrypointRequiredRuntime && ENTRYPOINT_REQUIRED_RUNTIMES.has(entrypointRequiredRuntime)) {
+    return {
+      code: "MISSING_ENTRYPOINT",
+      message: `Service "${name}" must specify "entrypoint" when using "${config.runtime ? "runtime" : "framework"}" "${config.runtime || config.framework}".`,
+      serviceName: name
+    };
+  }
   if (hasBuilderOrRuntime && !hasFramework && !hasEntrypoint) {
     return {
       code: "MISSING_ENTRYPOINT",
@@ -465,7 +544,7 @@ async function resolveConfiguredService(options) {
     routePrefixSource = "configured"
   } = options;
   const type = config.type || "web";
-  const trigger = type === "cron" ? "schedule" : type === "job" ? config.trigger : void 0;
+  const trigger = getEffectiveServiceTrigger(config);
   const rawEntrypoint = config.entrypoint;
   const moduleAttrParsed = typeof rawEntrypoint === "string" ? parsePyModuleAttrEntrypoint(rawEntrypoint) : null;
   const routingResult = resolveServiceRoutingConfig(name, config);
@@ -608,16 +687,16 @@ async function resolveConfiguredService(options) {
     schedule: config.schedule,
     handlerFunction: moduleAttrParsed?.attrName,
     topics,
-    envPrefix: config.envPrefix
+    env: config.env
   };
 }
-async function resolveAllConfiguredServices(services, fs, routePrefixSource = "configured") {
+async function resolveAllConfiguredServices(services, fs, routePrefixSource = "configured", options = {}) {
   const resolved = [];
   const errors = [];
   const webServicesByRoutePrefix = /* @__PURE__ */ new Map();
   for (const name of Object.keys(services)) {
     const serviceConfig = services[name];
-    const validationError = validateServiceConfig(name, serviceConfig);
+    const validationError = validateServiceConfig(name, serviceConfig, options);
     if (validationError) {
       errors.push(validationError);
       continue;
@@ -655,6 +734,16 @@ async function resolveAllConfiguredServices(services, fs, routePrefixSource = "c
         continue;
       }
     }
+    const explicitBackendEntrypointError = validateBackendFileEntrypoint(
+      name,
+      serviceConfig,
+      resolvedEntrypoint,
+      options
+    );
+    if (explicitBackendEntrypointError) {
+      errors.push(explicitBackendEntrypointError);
+      continue;
+    }
     let resolvedConfig = serviceConfig;
     if (!serviceConfig.framework && resolvedEntrypoint) {
       if (resolvedEntrypoint.isDirectory) {
@@ -711,6 +800,16 @@ async function resolveAllConfiguredServices(services, fs, routePrefixSource = "c
         }
       }
     }
+    const backendEntrypointError = validateBackendFileEntrypoint(
+      name,
+      resolvedConfig,
+      resolvedEntrypoint,
+      options
+    );
+    if (backendEntrypointError) {
+      errors.push(backendEntrypointError);
+      continue;
+    }
     const service = await resolveConfiguredService({
       name,
       config: resolvedConfig,
@@ -736,8 +835,49 @@ async function resolveAllConfiguredServices(services, fs, routePrefixSource = "c
     }
     resolved.push(service);
   }
+  const servicesByName = new Map(resolved.map((s) => [s.name, s]));
+  for (const service of resolved) {
+    if (!service.env)
+      continue;
+    validateEnvRefs(
+      service.env,
+      `Service "${service.name}" env`,
+      servicesByName,
+      errors,
+      service.name
+    );
+  }
+  if (options.rootEnv) {
+    validateEnvRefs(options.rootEnv, "env", servicesByName, errors);
+    for (const service of resolved) {
+      service.env = { ...options.rootEnv, ...service.env ?? {} };
+    }
+  }
   return { services: resolved, errors };
 }
+function validateEnvRefs(env, pathPrefix, servicesByName, errors, serviceName) {
+  for (const [envVarName, envVar] of Object.entries(env)) {
+    if (envVar.type !== "service-ref")
+      continue;
+    const refName = envVar.service;
+    const target = servicesByName.get(refName);
+    if (!target) {
+      errors.push({
+        code: "UNKNOWN_SERVICE_REF",
+        message: `${pathPrefix}["${envVarName}"] references unknown service "${refName}".`,
+        ...serviceName ? { serviceName } : {}
+      });
+      continue;
+    }
+    if (target.type !== "web") {
+      errors.push({
+        code: "INVALID_SERVICE_REF_TYPE",
+        message: `${pathPrefix}["${envVarName}"] references service "${refName}" which is a ${target.type} service and has no URL. Only web services can be referenced.`,
+        ...serviceName ? { serviceName } : {}
+      });
+    }
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   resolveAllConfiguredServices,

package/dist/services/types.d.ts

@@ -1,7 +1,7 @@
 import type { Route } from '@vercel/routing-utils';
-import type { ExperimentalServiceConfig, ExperimentalServiceGroups, ExperimentalServices, ServiceRuntime, ServiceType, Service, Builder } from '@vercel/build-utils';
+import type { EnvVar, EnvVars, ExperimentalServiceConfig, ExperimentalServiceGroups, ExperimentalServices, ServiceConfig, Services, ServiceRuntime, ServiceType, ServiceRefEnvVar, Service, Builder } from '@vercel/build-utils';
 import type { DetectorFilesystem } from '../detectors/filesystem';
-export type { ExperimentalServiceConfig, ExperimentalServiceGroups, ExperimentalServices, ServiceRuntime, ServiceType, Service, Builder, };
+export type { EnvVar, EnvVars, ExperimentalServiceConfig, ExperimentalServiceGroups, ExperimentalServices, ServiceConfig, Services, ServiceRuntime, ServiceType, ServiceRefEnvVar, Service, Builder, };
 /**
  * @deprecated Use `Service` instead
  */
@@ -34,24 +34,26 @@ export interface ServicesRoutes {
      */
     workers: Route[];
 }
-export type ServicesConfig = ExperimentalServices;
+export type ConfiguredServices = Services | ExperimentalServices;
+export type InferredServicesConfig = ExperimentalServices;
 export interface ResolvedServicesResult {
     services: Service[];
     source: DetectServicesSource;
+    useImplicitEnvInjection: boolean;
     routes: ServicesRoutes;
     errors: ServiceDetectionError[];
     warnings: ServiceDetectionWarning[];
 }
 export interface InferredServicesResult {
     source: 'layout' | 'procfile' | 'railway';
-    config: ServicesConfig;
+    config: InferredServicesConfig;
     services: Service[];
     warnings: ServiceDetectionWarning[];
 }
 export interface DetectServicesResult extends ResolvedServicesResult {
     /**
      * Source of service definitions:
-     * - `configured`: loaded from explicit project configuration (currently `vercel.json#experimentalServices`)
+     * - `configured`: loaded from explicit project configuration (`vercel.json#services` or legacy `experimentalServices`)
      * - `auto-detected`: inferred from project structure
      */
     resolved: ResolvedServicesResult;

package/dist/services/utils.d.ts

@@ -1,8 +1,12 @@
 import { INTERNAL_SERVICE_PREFIX, getInternalServiceFunctionPath, getInternalServiceCronPathPrefix, getInternalServiceCronPath } from '@vercel/build-utils';
 import type { DetectorFilesystem } from '../detectors/filesystem';
-import type { ServiceRuntime, ExperimentalServices, ServiceDetectionError, ResolvedService } from './types';
+import type { EnvVars, ServiceRuntime, ExperimentalServices, Services, ServiceDetectionError, ResolvedService } from './types';
 export { INTERNAL_SERVICE_PREFIX, getInternalServiceFunctionPath, getInternalServiceCronPathPrefix, getInternalServiceCronPath, };
 export declare function hasFile(fs: DetectorFilesystem, filePath: string): Promise<boolean>;
+export declare function isPublicServicesEnabled(): boolean;
+export declare function validateServicesConfigGate(config: {
+    services?: Services;
+} | null | undefined): ServiceDetectionError | null;
 /**
  * Reserved internal namespace used by the dev queue proxy.
  */
@@ -53,7 +57,9 @@ export declare function inferServiceRuntime(config: {
 }): ServiceRuntime | undefined;
 export interface ReadVercelConfigResult {
     config: {
+        services?: Services;
         experimentalServices?: ExperimentalServices;
+        env?: Record<string, string> | EnvVars;
     } | null;
     error: ServiceDetectionError | null;
 }

package/dist/services/utils.js

@@ -41,9 +41,11 @@ __export(utils_exports, {
   inferRuntimeFromFramework: () => inferRuntimeFromFramework,
   inferServiceRuntime: () => inferServiceRuntime,
   isFrontendFramework: () => isFrontendFramework,
+  isPublicServicesEnabled: () => isPublicServicesEnabled,
   isRouteOwningBuilder: () => isRouteOwningBuilder,
   isStaticBuild: () => isStaticBuild,
-  readVercelConfig: () => readVercelConfig
+  readVercelConfig: () => readVercelConfig,
+  validateServicesConfigGate: () => validateServicesConfigGate
 });
 module.exports = __toCommonJS(utils_exports);
 var import_framework_helpers = require("@vercel/build-utils/dist/framework-helpers");
@@ -56,6 +58,18 @@ async function hasFile(fs, filePath) {
     return false;
   }
 }
+function isPublicServicesEnabled() {
+  return process.env.VERCEL_USE_SERVICES === "1" || process.env.VERCEL_USE_SERVICES?.toLowerCase() === "true";
+}
+function validateServicesConfigGate(config) {
+  if (config?.services !== void 0 && !isPublicServicesEnabled()) {
+    return {
+      code: "INVALID_VERCEL_CONFIG",
+      message: "Invalid vercel.json - should NOT have additional property `services`. Please remove it."
+    };
+  }
+  return null;
+}
 const INTERNAL_QUEUES_PREFIX = "/_svc/_queues";
 function normalizeInternalServiceEntrypoint(entrypoint) {
   const normalized = entrypoint.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\.[^/.]+$/, "");
@@ -140,6 +154,10 @@ async function readVercelConfig(fs) {
     try {
       const content = await fs.readFile("vercel.json");
       const config = JSON.parse(content.toString());
+      const gateError = validateServicesConfigGate(config);
+      if (gateError) {
+        return { config: null, error: gateError };
+      }
       return { config, error: null };
     } catch {
       return {
@@ -157,6 +175,10 @@ async function readVercelConfig(fs) {
       const { parse: tomlParse } = await import("smol-toml");
       const content = await fs.readFile("vercel.toml");
       const config = tomlParse(content.toString());
+      const gateError = validateServicesConfigGate(config);
+      if (gateError) {
+        return { config: null, error: gateError };
+      }
       return { config, error: null };
     } catch {
       return {
@@ -185,7 +207,9 @@ async function readVercelConfig(fs) {
   inferRuntimeFromFramework,
   inferServiceRuntime,
   isFrontendFramework,
+  isPublicServicesEnabled,
   isRouteOwningBuilder,
   isStaticBuild,
-  readVercelConfig
+  readVercelConfig,
+  validateServicesConfigGate
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/fs-detectors",
-  "version": "6.2.1",
+  "version": "6.3.0",
   "description": "Vercel filesystem detectors",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,10 +20,10 @@
     "minimatch": "3.1.2",
     "semver": "6.3.1",
     "smol-toml": "1.5.2",
-    "@vercel/error-utils": "2.1.0",
-    "@vercel/frameworks": "3.25.1",
     "@vercel/routing-utils": "6.2.0",
-    "@vercel/build-utils": "13.22.1"
+    "@vercel/frameworks": "3.26.0",
+    "@vercel/error-utils": "2.1.0",
+    "@vercel/build-utils": "13.24.0"
   },
   "devDependencies": {
     "@types/glob": "7.2.0",