Add experimental.runtimeServerDeploymentId (#86865)

If this is set, `process.env.NEXT_DEPLOYMENT_ID` is available at runtime, and we don't need to inline the build-time value into the build output.

This is currently true for Node.js routes, and will also be the case for edge routes once #86769 is merged.

`experimental.runtimeServerDeploymentId` defaults to true when deploying on Vercel and `NEXT_DEPLOYMENT_ID` is set.

- [x] Perform `config.deploymentId = process.env.NEXT_DEPLOYMENT_ID` in the right places in the server

This brings us to this state regarding the deployoment ids in the output (notice the exclusion field):

<img width="628" height="323" alt="Bildschirmfoto 2025-12-05 um 21 17 53" src="https://github.com/user-attachments/assets/6e35997f-3f81-4da4-880e-d1d1984f7272" />

Author: mischnic

packages/next/errors.json

@@ -967,5 +967,7 @@
   "966": "Expected process.nextTick to reject invalid arguments",
   "967": "The key \"%s\" under \"env\" in %sconfig is not allowed. https://nextjs.org/docs/messages/env-key-not-allowed",
   "968": "Invariant: getNextConfigEdge must only be called in edge runtime",
-  "969": "Invariant: nextConfig couldn't be loaded"
+  "969": "Invariant: nextConfig couldn't be loaded",
+  "970": "process.env.NEXT_DEPLOYMENT_ID is missing but runtimeServerDeploymentId is enabled",
+  "971": "The NEXT_DEPLOYMENT_ID environment variable value \"%s\" does not match the provided deploymentId \"%s\" in the config."
 }

packages/next/src/build/define-env.ts

@@ -61,12 +61,12 @@ interface SerializedDefineEnv {
  * Serializes the DefineEnv config so that it can be inserted into the code by Webpack/Turbopack, JSON stringifies each value.
  */
 function serializeDefineEnv(defineEnv: DefineEnv): SerializedDefineEnv {
-  const defineEnvStringified: SerializedDefineEnv = {}
-  for (const key in defineEnv) {
-    const value = defineEnv[key]
-    defineEnvStringified[key] = JSON.stringify(value)
-  }
-
+  const defineEnvStringified: SerializedDefineEnv = Object.fromEntries(
+    Object.entries(defineEnv).map(([key, value]) => [
+      key,
+      JSON.stringify(value),
+    ])
+  )
   return defineEnvStringified
 }
 
@@ -167,9 +167,24 @@ export function getDefineEnv({
     'process.env.__NEXT_CACHE_COMPONENTS': isCacheComponentsEnabled,
     'process.env.__NEXT_USE_CACHE': isUseCacheEnabled,
 
-    'process.env.NEXT_DEPLOYMENT_ID': config.experimental?.useSkewCookie
-      ? false
-      : config.deploymentId || false,
+    ...(isClient
+      ? {
+          // TODO use `globalThis.NEXT_DEPLOYMENT_ID` on client to still support accessing
+          // process.env.NEXT_DEPLOYMENT_ID in userland
+          'process.env.NEXT_DEPLOYMENT_ID': config.experimental?.useSkewCookie
+            ? false
+            : config.deploymentId || false,
+        }
+      : config.experimental?.runtimeServerDeploymentId
+        ? {
+            // Don't inline at all, keep process.env.NEXT_DEPLOYMENT_ID as is
+          }
+        : {
+            'process.env.NEXT_DEPLOYMENT_ID': config.experimental?.useSkewCookie
+              ? false
+              : config.deploymentId || false,
+          }),
+
     // Propagates the `__NEXT_EXPERIMENTAL_STATIC_SHELL_DEBUGGING` environment
     // variable to the client.
     'process.env.__NEXT_EXPERIMENTAL_STATIC_SHELL_DEBUGGING':
@@ -372,8 +387,10 @@ export function getDefineEnv({
     for (const key in nextConfigEnv) {
       serializedDefineEnv[key] = safeKey(key)
     }
-    for (const key of ['process.env.NEXT_DEPLOYMENT_ID']) {
-      serializedDefineEnv[key] = safeKey(key)
+    if (!config.experimental.runtimeServerDeploymentId) {
+      for (const key of ['process.env.NEXT_DEPLOYMENT_ID']) {
+        serializedDefineEnv[key] = safeKey(key)
+      }
     }
   }
 

packages/next/src/build/index.ts

@@ -989,7 +989,7 @@ export default async function build(
       // when using compile mode static env isn't inlined so we
       // need to populate in normal runtime env
       if (isCompileMode || isGenerateMode) {
-        populateStaticEnv(config)
+        populateStaticEnv(config, config.deploymentId)
       }
 
       const customRoutes: CustomRoutes = await nextBuildSpan

packages/next/src/build/templates/app-page.ts

@@ -170,6 +170,7 @@ export async function handler(
     nextConfig,
     parsedUrl,
     interceptionRoutePatterns,
+    deploymentId,
   } = prepareResult
 
   const normalizedSrcPage = normalizeAppPath(srcPage)
@@ -559,7 +560,7 @@ export async function handler(
           trailingSlash: nextConfig.trailingSlash,
           images: nextConfig.images,
           previewProps: prerenderManifest.preview,
-          deploymentId: nextConfig.deploymentId,
+          deploymentId: deploymentId,
           enableTainting: nextConfig.experimental.taint,
           htmlLimitedBots: nextConfig.htmlLimitedBots,
           reactMaxHeadersLength: nextConfig.reactMaxHeadersLength,

packages/next/src/build/templates/edge-ssr-app.ts

@@ -81,6 +81,7 @@ async function requestHandler(
     resolvedPathname,
     interceptionRoutePatterns,
     routerServerContext,
+    deploymentId,
   } = prepareResult
 
   // Initialize the cache handlers interface.
@@ -137,7 +138,7 @@ async function requestHandler(
       trailingSlash: nextConfig.trailingSlash,
       images: nextConfig.images,
       previewProps: prerenderManifest.preview,
-      deploymentId: nextConfig.deploymentId,
+      deploymentId,
       enableTainting: nextConfig.experimental.taint,
       htmlLimitedBots: nextConfig.htmlLimitedBots,
       reactMaxHeadersLength: nextConfig.reactMaxHeadersLength,

packages/next/src/lib/inline-static-env.ts

@@ -17,7 +17,7 @@ export async function inlineStaticEnv({
   config: NextConfigComplete
 }) {
   const nextConfigEnv = getNextConfigEnv(config)
-  const staticEnv = getStaticEnv(config)
+  const staticEnv = getStaticEnv(config, config.deploymentId)
 
   const serverDir = path.join(distDir, 'server')
   const serverChunks = await glob('**/*.{js,json,js.map}', {

packages/next/src/lib/static-env.ts

@@ -53,22 +53,26 @@ export function getNextConfigEnv(
   return defineEnv
 }
 
-export function getStaticEnv(config: NextConfigComplete | NextConfigRuntime) {
+export function getStaticEnv(
+  config: NextConfigComplete | NextConfigRuntime,
+  deploymentId: string
+) {
   const staticEnv: Record<string, string | undefined> = {
     ...getNextPublicEnvironmentVariables(),
     ...getNextConfigEnv(config),
-    'process.env.NEXT_DEPLOYMENT_ID': config.deploymentId || '',
+    'process.env.NEXT_DEPLOYMENT_ID': deploymentId,
   }
   return staticEnv
 }
 
 export function populateStaticEnv(
-  config: NextConfigComplete | NextConfigRuntime
+  config: NextConfigComplete | NextConfigRuntime,
+  deploymentId: string
 ) {
   // since inlining comes after static generation we need
   // to ensure this value is assigned to process env so it
   // can still be accessed
-  const staticEnv = getStaticEnv(config)
+  const staticEnv = getStaticEnv(config, deploymentId)
   for (const key in staticEnv) {
     const innerKey = key.split('.').pop() || ''
     if (!process.env[innerKey]) {

packages/next/src/server/base-server.ts

@@ -447,6 +447,24 @@ export default abstract class Server<
     // TODO: should conf be normalized to prevent missing
     // values from causing issues as this can be user provided
     this.nextConfig = conf as NextConfigRuntime
+
+    let deploymentId
+    if (this.nextConfig.experimental.runtimeServerDeploymentId) {
+      if (!process.env.NEXT_DEPLOYMENT_ID) {
+        throw new Error(
+          'process.env.NEXT_DEPLOYMENT_ID is missing but runtimeServerDeploymentId is enabled'
+        )
+      }
+      deploymentId = process.env.NEXT_DEPLOYMENT_ID
+    } else {
+      let id = this.nextConfig.experimental.useSkewCookie
+        ? ''
+        : this.nextConfig.deploymentId || ''
+
+      deploymentId = id
+      process.env.NEXT_DEPLOYMENT_ID = id
+    }
+
     this.hostname = hostname
     if (this.hostname) {
       // we format the hostname so that it can be fetched
@@ -501,13 +519,12 @@ export default abstract class Server<
     }
 
     this.nextFontManifest = this.getNextFontManifest()
-    process.env.NEXT_DEPLOYMENT_ID = this.nextConfig.deploymentId || ''
 
     this.renderOpts = {
       dir: this.dir,
       supportsDynamicResponse: true,
       trailingSlash: this.nextConfig.trailingSlash,
-      deploymentId: this.nextConfig.deploymentId,
+      deploymentId: deploymentId,
       poweredByHeader: this.nextConfig.poweredByHeader,
       generateEtags,
       previewProps: this.getPrerenderManifest().preview,

packages/next/src/server/config-schema.ts

@@ -347,6 +347,7 @@ export const experimentalSchema = {
     .optional(),
   lockDistDir: z.boolean().optional(),
   hideLogsAfterAbort: z.boolean().optional(),
+  runtimeServerDeploymentId: z.boolean().optional(),
 }
 
 export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>

packages/next/src/server/config-shared.ts

@@ -836,6 +836,14 @@ export interface ExperimentalConfig {
    * @default false
    */
   hideLogsAfterAbort?: boolean
+
+  /**
+   * Whether `process.env.NEXT_DEPLOYMENT_ID` is available at runtime in the server (and `next
+   * build` doesn't need to embed the deployment ID value into the build output).
+   *
+   * @default false
+   */
+  runtimeServerDeploymentId?: boolean
 }
 
 export type ExportPathMap = {
@@ -1586,8 +1594,8 @@ export async function normalizeConfig(phase: string, config: any) {
 //   };
 // };
 export interface NextConfigRuntime {
-  // TODO remove in some cases
-  deploymentId: NextConfigComplete['deploymentId']
+  // Can be undefined, particularly when experimental.runtimeServerDeploymentId is true
+  deploymentId?: NextConfigComplete['deploymentId']
 
   configFileName?: string
   // Should only be included when using isExperimentalCompile
@@ -1652,6 +1660,7 @@ export interface NextConfigRuntime {
     | 'proxyClientMaxBodySize'
     | 'proxyTimeout'
     | 'testProxy'
+    | 'runtimeServerDeploymentId'
   > & {
     // Pick on @internal fields generates invalid .d.ts files
     /** @internal */
@@ -1706,14 +1715,17 @@ export function getNextConfigRuntime(
         proxyClientMaxBodySize: ex.proxyClientMaxBodySize,
         proxyTimeout: ex.proxyTimeout,
         testProxy: ex.testProxy,
+        runtimeServerDeploymentId: ex.runtimeServerDeploymentId,
 
         trustHostHeader: ex.trustHostHeader,
         isExperimentalCompile: ex.isExperimentalCompile,
       } satisfies Requiredish<NextConfigRuntime['experimental']>)
     : {}
 
   let runtimeConfig: Requiredish<NextConfigRuntime> = {
-    deploymentId: config.deploymentId,
+    deploymentId: config.experimental.runtimeServerDeploymentId
+      ? ''
+      : config.deploymentId,
 
     configFileName: undefined,
     env: undefined,