Use serialized next config for prod server

.github/workflows/build_and_test.yml

@@ -956,6 +956,7 @@ jobs:
       afterBuild: |
         export __NEXT_EXPERIMENTAL_PPR=true # for compatibility with the existing tests
         export __NEXT_EXPERIMENTAL_CACHE_COMPONENTS=true
+        export __NEXT_EXPERIMENTAL_SERIALIZE_NEXT_CONFIG_FOR_PRODUCTION=true
         export NEXT_EXTERNAL_TESTS_FILTERS="test/experimental-tests-manifest.json"
 
         node run-tests.js \
@@ -978,6 +979,7 @@ jobs:
       afterBuild: |
         export __NEXT_EXPERIMENTAL_PPR=true # for compatibility with the existing tests
         export __NEXT_EXPERIMENTAL_CACHE_COMPONENTS=true
+        export __NEXT_EXPERIMENTAL_SERIALIZE_NEXT_CONFIG_FOR_PRODUCTION=true
         export NEXT_EXTERNAL_TESTS_FILTERS="test/experimental-tests-manifest.json"
         export NEXT_TEST_MODE=dev
 
@@ -1002,6 +1004,7 @@ jobs:
       afterBuild: |
         export __NEXT_EXPERIMENTAL_PPR=true # for compatibility with the existing tests
         export __NEXT_EXPERIMENTAL_CACHE_COMPONENTS=true
+        export __NEXT_EXPERIMENTAL_SERIALIZE_NEXT_CONFIG_FOR_PRODUCTION=true
         export NEXT_EXTERNAL_TESTS_FILTERS="test/experimental-tests-manifest.json"
         export NEXT_TEST_MODE=start
 

packages/next/errors.json

@@ -808,5 +808,6 @@
   "807": "Expected a %s response header.",
   "808": "Invalid binary HMR message: insufficient data (expected %s bytes, got %s)",
   "809": "Invalid binary HMR message of type %s",
-  "810": "React debug channel stream error"
+  "810": "React debug channel stream error",
+  "811": "Failed to load serialized config \"%s\"."
 }

packages/next/src/build/index.ts

@@ -61,6 +61,7 @@ import {
   PRERENDER_MANIFEST,
   REACT_LOADABLE_MANIFEST,
   ROUTES_MANIFEST,
+  SERIALIZED_CONFIG_FILE,
   SERVER_DIRECTORY,
   SERVER_FILES_MANIFEST,
   STATIC_STATUS_PAGES,
@@ -2723,6 +2724,36 @@ export default async function build(
         requiredServerFilesManifest
       )
 
+      // The required-server-files manifest contains serialized config, which can
+      // be loaded by the prod server. However, when a custom distDir is set,
+      // the prod server will not know the distDir until loading the config.
+      // Therefore we write the serialized config to the same directory as the
+      // original config file.
+      if (
+        config.output !== 'standalone' &&
+        config.distDir !== '.next' &&
+        // Use nullish coalescing (??) since we don't want to return when it's false.
+        (config.experimental?.serializeNextConfigForProduction ??
+          // This flag is used to be enabled on the tests.
+          process.env
+            .__NEXT_EXPERIMENTAL_SERIALIZE_NEXT_CONFIG_FOR_PRODUCTION ===
+            'true')
+      ) {
+        const serializedConfigPath = path.join(
+          // Write to the same directory as the original config file.
+          config.configFile ? path.dirname(config.configFile) : dir,
+          SERIALIZED_CONFIG_FILE
+        )
+        await fs.writeFile(
+          serializedConfigPath,
+          JSON.stringify({
+            // To match the format of required server files manifest.
+            version: 1,
+            config: requiredServerFilesManifest.config,
+          })
+        )
+      }
+
       // we don't need to inline for turbopack build as
       // it will handle it's own caching separate of compile
       if (isGenerateMode && !isTurbopack) {

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

@@ -526,6 +526,7 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
           ])
           .optional(),
         optimizeRouterScrolling: z.boolean().optional(),
+        serializeNextConfigForProduction: z.boolean().optional(),
       })
       .optional(),
     exportPathMap: z

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

@@ -818,6 +818,16 @@ export interface ExperimentalConfig {
    * instead of `{distDir}`.
    */
   isolatedDevBuild?: boolean
+
+  /**
+   * When enabled, the production server will use the serialized config file
+   * instead of the original config file. This can save the time of loading the
+   * config file, especially when you are using `next.config.ts`. When the `distDir`
+   * is set, the serialized config `next-config-serialized.json` will be written to
+   * the same directory as the original config file. This is because Next.js doesn't
+   * know the `distDir` until loading the config.
+   */
+  serializeNextConfigForProduction?: boolean
 }
 
 export type ExportPathMap = {
@@ -1495,6 +1505,10 @@ export const defaultConfig = Object.freeze({
     browserDebugInfoInTerminal: false,
     optimizeRouterScrolling: false,
     isolatedDevBuild: false,
+    serializeNextConfigForProduction:
+      // This flag is used to be enabled on the tests.
+      process.env.__NEXT_EXPERIMENTAL_SERIALIZE_NEXT_CONFIG_FOR_PRODUCTION ===
+      'true',
   },
   htmlLimitedBots: undefined,
   bundlePagesRouterDependencies: false,

packages/next/src/server/config.ts

@@ -1,5 +1,13 @@
-import { existsSync } from 'fs'
-import { basename, extname, join, relative, isAbsolute, resolve } from 'path'
+import { existsSync, readFileSync } from 'fs'
+import {
+  basename,
+  extname,
+  join,
+  relative,
+  isAbsolute,
+  resolve,
+  dirname,
+} from 'path'
 import { pathToFileURL } from 'url'
 import findUp from 'next/dist/compiled/find-up'
 import * as Log from '../build/output/log'
@@ -9,6 +17,9 @@ import {
   PHASE_DEVELOPMENT_SERVER,
   PHASE_EXPORT,
   PHASE_PRODUCTION_BUILD,
+  PHASE_PRODUCTION_SERVER,
+  SERVER_FILES_MANIFEST,
+  SERIALIZED_CONFIG_FILE,
   type PHASE_TYPE,
 } from '../shared/lib/constants'
 import { defaultConfig, normalizeConfig } from './config-shared'
@@ -1344,6 +1355,93 @@ export default async function loadConfig(
     return standaloneConfig
   }
 
+  let path: string | undefined
+  // During prod server, we can load from the serialized config.
+  if (phase === PHASE_PRODUCTION_SERVER) {
+    // Try load from ".next" dir since we don't know the
+    // distDir until loading the config.
+    try {
+      const possiblyServerFilesManifestPath = join(
+        dir,
+        '.next',
+        SERVER_FILES_MANIFEST
+      )
+      if (existsSync(possiblyServerFilesManifestPath)) {
+        const parsed = JSON.parse(
+          readFileSync(possiblyServerFilesManifestPath, 'utf8')
+        )
+        const config: NextConfigComplete = parsed.config
+
+        if (
+          // Don't return here and will eventually fall back to loading the config.
+          // Use nullish coalescing (??) since we don't want to return when it's false.
+          config?.experimental?.serializeNextConfigForProduction ??
+          // This flag is used to be enabled on the tests.
+          process.env
+            .__NEXT_EXPERIMENTAL_SERIALIZE_NEXT_CONFIG_FOR_PRODUCTION === 'true'
+        ) {
+          // Cache the config
+          configCache.set(cacheKey, {
+            config,
+            rawConfig: config,
+            configuredExperimentalFeatures: [],
+          })
+
+          return config
+        }
+      }
+    } catch {
+      // Continue to next option
+    }
+
+    // If the custom distDir is set, we write the serialized config
+    // to the same directory as the original config file.
+    path = await findUp(CONFIG_FILES, { cwd: dir })
+    const targetDir = path ? dirname(path) : dir
+
+    // Even though serializeNextConfigForProduction might be disabled, we still need to check
+    // the existSync because there's no way to know if serializeNextConfigForProduction
+    // is disabled until we load the config.
+    const serializedConfigPath = join(targetDir, SERIALIZED_CONFIG_FILE)
+    try {
+      if (existsSync(serializedConfigPath)) {
+        const parsed = JSON.parse(readFileSync(serializedConfigPath, 'utf8'))
+        const config: NextConfigComplete = parsed.config
+
+        if (
+          // Don't return here and will eventually fall back to loading the config.
+          // Use nullish coalescing (??) since we don't want to return when it's false.
+          config?.experimental?.serializeNextConfigForProduction ??
+          // This flag is used to be enabled on the tests.
+          process.env
+            .__NEXT_EXPERIMENTAL_SERIALIZE_NEXT_CONFIG_FOR_PRODUCTION === 'true'
+        ) {
+          // Cache the config
+          configCache.set(cacheKey, {
+            config,
+            rawConfig: config,
+            configuredExperimentalFeatures: [],
+          })
+
+          return config
+        }
+      }
+    } catch (cause) {
+      if (
+        // This flag is used to be enabled on the tests.
+        process.env.__NEXT_EXPERIMENTAL_SERIALIZE_NEXT_CONFIG_FOR_PRODUCTION ===
+        'true'
+      ) {
+        throw new Error(
+          `Failed to load serialized config "${serializedConfigPath}".`,
+          { cause }
+        )
+      }
+    }
+
+    // Fall back to loading the config.
+  }
+
   const curLog = silent
     ? {
         warn: () => {},
@@ -1389,7 +1487,7 @@ export default async function loadConfig(
     return config
   }
 
-  const path = await findUp(CONFIG_FILES, { cwd: dir })
+  path ??= await findUp(CONFIG_FILES, { cwd: dir })
 
   // If config file was found
   if (path?.length) {

packages/next/src/shared/lib/constants.ts

@@ -96,6 +96,7 @@ export const PRERENDER_MANIFEST = 'prerender-manifest.json'
 export const ROUTES_MANIFEST = 'routes-manifest.json'
 export const IMAGES_MANIFEST = 'images-manifest.json'
 export const SERVER_FILES_MANIFEST = 'required-server-files.json'
+export const SERIALIZED_CONFIG_FILE = 'next-config-serialized.json'
 export const DEV_CLIENT_PAGES_MANIFEST = '_devPagesManifest.json'
 export const MIDDLEWARE_MANIFEST = 'middleware-manifest.json'
 export const TURBOPACK_CLIENT_MIDDLEWARE_MANIFEST =

test/e2e/app-dir/nx-handling/apps/next-nx-test/next.config.js

@@ -10,6 +10,13 @@ const nextConfig = {
   // Use this to set Nx-specific options
   // See: https://nx.dev/recipes/next/next-config-setup
   nx: {},
+  experimental: {
+    // Disable because nx tries to copy the config to the dist dir
+    // and expect to load the config inside the dist dir again.
+    // In this case, the `distDir` will be relative to the original config,
+    // not the config inside the dist dir, and cause distDir path mismatch.
+    serializeNextConfigForProduction: false,
+  },
 }
 
 const plugins = [

test/e2e/config-schema-check/index.test.ts

@@ -58,8 +58,16 @@ describe('next.config.js schema validating - invalid config', () => {
 
       expect(output).toContain('Invalid next.config.js options detected')
       expect(output).toContain('badKey')
-      // for next start and next build we both display the warnings
-      expect(warningTimes).toBe(isNextStart ? 2 : 1)
+      if (
+        process.env.__NEXT_EXPERIMENTAL_SERIALIZE_NEXT_CONFIG_FOR_PRODUCTION ===
+        'true'
+      ) {
+        // With serialized config, warnings only appear during build, not during start
+        expect(warningTimes).toBe(1)
+      } else {
+        // for next start and next build we both display the warnings
+        expect(warningTimes).toBe(isNextStart ? 2 : 1)
+      }
 
       return 'success'
     }, 'success')

test/e2e/next-phase/index.test.ts

@@ -23,10 +23,16 @@ describe('next-phase', () => {
   if (skipped) return
 
   it('should render page with next phase correctly', async () => {
+    const isSerializedNextConfigForProduction =
+      process.env.__NEXT_EXPERIMENTAL_SERIALIZE_NEXT_CONFIG_FOR_PRODUCTION ===
+      'true'
     const phases = {
       dev: 'phase-development-server',
       build: 'phase-production-build',
-      start: 'phase-production-server',
+      start: isSerializedNextConfigForProduction
+        ? // Serialized next config will use the config from build.
+          'phase-production-build'
+        : 'phase-production-server',
     }
     const currentPhase = isNextDev ? phases.dev : phases.build
     const nonExistedPhase = isNextDev ? phases.build : phases.dev
@@ -40,7 +46,9 @@ describe('next-phase', () => {
     if (isNextDev) {
       expect(next.cliOutput).not.toContain(phases.start)
     } else {
-      expect(next.cliOutput).toContain(phases.start)
+      if (isSerializedNextConfigForProduction) {
+        expect(next.cliOutput).toContain(phases.start)
+      }
     }
   })
 })