stabilize experimental.enablePrerenderSourcemaps (#84916)

As part of stabilizing cacheComponents, we are also stabilizing
supporting flags. This flag has been enabled with cacheComponents for
some time and so we are moving it out of experimental.

It will continue to be enabled by default if you are using
cacheComponents. Otherwise, it can be opted into independently via next
config.

Closes https://linear.app/vercel/issue/NDX-1048
Closes #80317

---------

Co-authored-by: Sebastian "Sebbie" Silbermann <[email protected]>

Author: ztanner

docs/01-app/02-guides/memory-usage.mdx

@@ -125,6 +125,10 @@ Generating source maps consumes extra memory during the build process.
 
 You can disable source map generation by adding `productionBrowserSourceMaps: false` and `experimental.serverSourceMaps: false` to your Next.js configuration.
 
+When using the `experimental.cacheComponents` feature, Next.js will use source maps by default during the prerender phase of `next build`.
+If you consistently encounter memory issues during that phase (after "Generating static pages"),
+you can try disabling source maps in that phase by adding `enablePrerenderSourceMaps: false` to your Next.js configuration.
+
 > **Good to know**: Some plugins may turn on source maps and may require custom configuration to disable.
 
 ## Edge memory issues

docs/01-app/03-api-reference/06-cli/next.mdx

@@ -240,7 +240,7 @@ This enables several experimental options to make debugging easier:
 - Generates source maps for server bundles:
   - `experimental.serverSourceMaps = true`
 - Enables source map consumption in child processes used for prerendering:
-  - `experimental.enablePrerenderSourceMaps = true`
+  - `enablePrerenderSourceMaps = true`
 - Continues building even after the first prerender error, so you can see all issues at once:
   - `experimental.prerenderEarlyExit = false`
 

packages/next/src/build/index.ts

@@ -853,7 +853,7 @@ export function createStaticWorker(
       progress?.clear()
     },
     debuggerPortOffset,
-    enableSourceMaps: config.experimental.enablePrerenderSourceMaps,
+    enableSourceMaps: config.enablePrerenderSourceMaps,
     // remove --max-old-space-size flag as it can cause memory issues.
     isolatedMemory: true,
     enableWorkerThreads: config.experimental.workerThreads,

packages/next/src/export/index.ts

@@ -413,7 +413,7 @@ async function exportAppImpl(
       (process.env.TURBOPACK
         ? nextConfig.experimental.turbopackMinify === false
         : nextConfig.experimental.serverMinification === false) &&
-      nextConfig.experimental.enablePrerenderSourceMaps === true,
+      nextConfig.enablePrerenderSourceMaps === true,
   }
 
   // We need this for server rendering the Link component.

packages/next/src/export/worker.ts

@@ -339,7 +339,7 @@ export async function exportPages(
 
   installGlobalBehaviors(nextConfig)
 
-  if (nextConfig.experimental.enablePrerenderSourceMaps) {
+  if (nextConfig.enablePrerenderSourceMaps) {
     try {
       // Same as `next dev`
       // Limiting the stack trace to a useful amount of frames is handled by ignore-listing.

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

@@ -313,7 +313,6 @@ export const experimentalSchema = {
   optimizeServerReact: z.boolean().optional(),
   clientTraceMetadata: z.array(z.string()).optional(),
   serverMinification: z.boolean().optional(),
-  enablePrerenderSourceMaps: z.boolean().optional(),
   serverSourceMaps: z.boolean().optional(),
   useWasmBinary: z.boolean().optional(),
   useLightningcss: z.boolean().optional(),
@@ -468,6 +467,7 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
       .optional(),
     distDir: z.string().min(1).optional(),
     env: z.record(z.string(), z.union([z.string(), z.undefined()])).optional(),
+    enablePrerenderSourceMaps: z.boolean().optional(),
     excludeDefaultMomentLocales: z.boolean().optional(),
     experimental: z.strictObject(experimentalSchema).optional(),
     exportPathMap: z

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

@@ -625,12 +625,6 @@ export interface ExperimentalConfig {
    */
   serverMinification?: boolean
 
-  /**
-   * Enables source maps while generating static pages.
-   * Helps with errors during the prerender phase in `next build`.
-   */
-  enablePrerenderSourceMaps?: boolean
-
   /**
    * Enables source maps generation for the server production bundle.
    */
@@ -1260,6 +1254,12 @@ export interface NextConfig {
    */
   logging?: LoggingConfig | false
 
+  /**
+   * Enables source maps while generating static pages.
+   * Helps with errors during the prerender phase in `next build`.
+   */
+  enablePrerenderSourceMaps?: boolean
+
   /**
    * period (in seconds) where the server allow to serve stale cache
    */
@@ -1385,6 +1385,8 @@ export const defaultConfig = Object.freeze({
   modularizeImports: undefined,
   outputFileTracingRoot: process.env.NEXT_PRIVATE_OUTPUT_TRACE_ROOT || '',
   allowedDevOrigins: undefined,
+  // Will default to cacheComponents value.
+  enablePrerenderSourceMaps: undefined,
   experimental: {
     adapterPath: process.env.NEXT_ADAPTER_PATH || undefined,
     useSkewCookie: false,
@@ -1435,8 +1437,6 @@ export const defaultConfig = Object.freeze({
     appNavFailHandling: false,
     prerenderEarlyExit: true,
     serverMinification: true,
-    // Will default to cacheComponents value.
-    enablePrerenderSourceMaps: undefined,
     serverSourceMaps: false,
     linkNoTouchStart: false,
     caseSensitiveRoutes: false,

packages/next/src/server/config.ts

@@ -707,6 +707,13 @@ function assignDefaultsAndValidate(
     configFileName,
     silent
   )
+  warnOptionHasBeenMovedOutOfExperimental(
+    result,
+    'enablePrerenderSourceMaps',
+    'enablePrerenderSourceMaps',
+    configFileName,
+    silent
+  )
 
   if ((result.experimental as any).outputStandalone) {
     if (!silent) {
@@ -1269,9 +1276,14 @@ function assignDefaultsAndValidate(
     result.experimental.mcpServer = true
   }
 
-  // TODO: remove once we've finished migrating internally to cacheComponents.
   if (result.experimental.cacheComponents) {
+    // TODO: remove once we've finished migrating internally to cacheComponents.
     result.experimental.ppr = true
+
+    // Prerender sourcemaps are enabled by default when using cacheComponents, unless explicitly disabled.
+    if (result.enablePrerenderSourceMaps === undefined) {
+      result.enablePrerenderSourceMaps = true
+    }
   }
 
   // "use cache" was originally implicitly enabled with the cacheComponents flag, so
@@ -1734,6 +1746,9 @@ function enforceExperimentalFeatures(
     debugPrerender &&
     (phase === PHASE_PRODUCTION_BUILD || phase === PHASE_EXPORT)
   ) {
+    // TODO: This is not an experimental feature, but should be enabled alongside other prerender debugging features.
+    config.enablePrerenderSourceMaps = true
+
     setExperimentalFeatureForDebugPrerender(
       config.experimental,
       'serverSourceMaps',
@@ -1748,13 +1763,6 @@ function enforceExperimentalFeatures(
       configuredExperimentalFeatures
     )
 
-    setExperimentalFeatureForDebugPrerender(
-      config.experimental,
-      'enablePrerenderSourceMaps',
-      true,
-      configuredExperimentalFeatures
-    )
-
     setExperimentalFeatureForDebugPrerender(
       config.experimental,
       'prerenderEarlyExit',
@@ -1810,22 +1818,6 @@ function enforceExperimentalFeatures(
     config.reactCompiler = true
     // TODO: Report if we enable non-experimental features via env
   }
-
-  if (
-    config.experimental.enablePrerenderSourceMaps === undefined &&
-    config.experimental.cacheComponents === true
-  ) {
-    config.experimental.enablePrerenderSourceMaps = true
-
-    if (configuredExperimentalFeatures) {
-      addConfiguredExperimentalFeature(
-        configuredExperimentalFeatures,
-        'enablePrerenderSourceMaps',
-        true,
-        'enabled by `experimental.cacheComponents`'
-      )
-    }
-  }
 }
 
 function addConfiguredExperimentalFeature<

test/e2e/app-dir/root-suspense-dynamic/fixtures/default/next.config.js

@@ -2,9 +2,10 @@
  * @type {import('next').NextConfig}
  */
 const nextConfig = {
+  enablePrerenderSourceMaps: false,
+
   experimental: {
     cacheComponents: true,
-    enablePrerenderSourceMaps: false,
   },
 }
 

test/e2e/app-dir/server-source-maps/fixtures/edge/next.config.js

@@ -2,9 +2,9 @@
  * @type {import('next').NextConfig}
  */
 const nextConfig = {
+  enablePrerenderSourceMaps: true,
   experimental: {
     cpus: 1,
-    enablePrerenderSourceMaps: true,
     serverSourceMaps: true,
   },
 }