Build with dev runtimes when --debug-prerender is set (#89834)

When running `next build --debug-prerender`, React owner stacks are now
captured and displayed in prerender error output. This makes it much
easier to diagnose which component triggered uncached I/O or accessed
request data without Suspense. Previously, `--debug-prerender` only
enabled source maps and disabled minification. Now it also auto-enables
`allowDevelopmentBuild` and sets `NODE_ENV=development`, which loads
React development builds where `captureOwnerStack()` is available.

The main challenge is that with `NODE_ENV=development`, both server and
client bundles include dev-only code paths (HMR, WebSocket connections,
dev overlay, debug channel, etc.) that expect a running dev server. We
don't want these when using `next start`. To solve this, we introduce
`process.env.__NEXT_DEV_SERVER`, an internal env var that is truthy only
during `next dev`. In client bundles, it's inlined at build time (`'1'`
for `next dev`, `''` for `next build`). In production server runtime
bundles, it's inlined as `''` for dead-code elimination. In development
server runtime bundles, it's left as a runtime check because those
bundles are shared between `next dev` (where it's set) and `next build
--debug-prerender` (where it's not). Meanwhile, `NODE_ENV` continues to
control React's dev/prod mode and error formatting, which is exactly
what we want for `--debug-prerender`.

This also replaces the previous `renderOpts.dev` / `workStore.dev`
pattern, which was unreliable because `RouteModule.isDev` was derived
from `NODE_ENV` at compile time. When `allowDevelopmentBuild` set
`NODE_ENV=development`, `isDev` would be compiled as `true` and
incorrectly activate all dev guards during `next start`.

Key changes:

- `config.ts` auto-enables `allowDevelopmentBuild` and sets
`NODE_ENV=development` when `--debug-prerender` is active
- `define-env.ts` inlines `__NEXT_DEV_SERVER` into all bundles (truthy
for dev, falsy for build) so dev-server features are dead-code
eliminated in production and `--debug-prerender` builds
- `next-dev.ts` and `next.ts` set `__NEXT_DEV_SERVER` in the process
environment for externalized server-side code
- `renderOpts.dev` and `workStore.dev` are removed — all consumers now
use `__NEXT_DEV_SERVER` (for dev-server features) or `NODE_ENV` (for
error formatting that should work in both dev and `--debug-prerender`
builds)
- `patch-error-inspect.ts` devirtualizes React server URLs in source map
URLs so they display as readable file paths

Author: unstubbable

AGENTS.md

@@ -246,6 +246,13 @@ See [Codebase structure](#codebase-structure) above for detailed explanations.
 - Use `DEBUG=next:*` for debug logging
 - Use `NEXT_TELEMETRY_DISABLED=1` when testing locally
 
+### `NODE_ENV` vs `__NEXT_DEV_SERVER`
+
+Both `next dev` and `next build --debug-prerender` produce bundles with `NODE_ENV=development`. Use `process.env.__NEXT_DEV_SERVER` to distinguish between them:
+
+- `process.env.NODE_ENV !== 'production'` — code that should exist in dev bundles but be eliminated from prod bundles. This is a build-time check.
+- `process.env.__NEXT_DEV_SERVER` — code that should only run with the dev server (`next dev`), not during `next build --debug-prerender` or `next start`.
+
 ## Commit and PR Style
 
 - Do NOT add "Generated with Claude Code" or co-author footers to commits or PRs

contributing/core/developing.md

@@ -100,6 +100,13 @@ $ pnpm unpack-next path/to/project
 
 The dev overlay is a feature of Next.js that allows you to see the internal state of the app including the errors. To learn more about contributing to the dev overlay, see the [Dev Overlay README.md](../../packages/next/src/client/components/react-dev-overlay/README.md).
 
+## `NODE_ENV` vs `__NEXT_DEV_SERVER`
+
+Both `next dev` and `next build --debug-prerender` produce bundles with `NODE_ENV=development`. Use `process.env.__NEXT_DEV_SERVER` to distinguish between them:
+
+- `process.env.NODE_ENV !== 'production'` — code that should exist in dev bundles but be eliminated from prod bundles. This is a build-time check.
+- `process.env.__NEXT_DEV_SERVER` — code that should only run with the dev server (`next dev`), not during `next build --debug-prerender` or `next start`.
+
 ## Recover disk space
 
 Rust builds quickly add up to a lot of disk space, you can clean up old artifacts with this command:

packages/next/next-runtime.webpack-config.js

@@ -209,8 +209,11 @@ module.exports = ({ dev, turbo, bundleType, experimental, ...rest }) => {
         'process.env.NEXT_MINIMAL': JSON.stringify('true'),
         'this.serverOptions.experimentalTestProxy': JSON.stringify(false),
         'this.minimalMode': JSON.stringify(true),
-        'this.renderOpts.dev': JSON.stringify(dev),
-        'renderOpts.dev': JSON.stringify(dev),
+        // Only inline __NEXT_DEV_SERVER in prod bundles (for dead-code
+        // elimination). Dev bundles must keep it as a runtime check because
+        // they're shared between `next dev` (where it's set) and `next build
+        // --debug-prerender` (where it's not).
+        ...(dev ? {} : { 'process.env.__NEXT_DEV_SERVER': JSON.stringify('') }),
         'process.env.NODE_ENV': JSON.stringify(
           dev ? 'development' : 'production'
         ),

packages/next/src/bin/next.ts

@@ -194,6 +194,10 @@ program
     'Enable CPU profiling. Profile is saved to .next/cpu-profiles/ on completion.'
   )
   .action((directory: string, options: NextBuildOptions) => {
+    if (options.debugPrerender) {
+      // @ts-expect-error not readonly
+      process.env.NODE_ENV = 'development'
+    }
     if (options.experimentalNextConfigStripTypes) {
       process.env.__NEXT_NODE_NATIVE_TS_LOADER_ENABLED = 'true'
     }

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

@@ -157,6 +157,7 @@ export function getDefineEnv({
       dev || config.experimental.allowDevelopmentBuild
         ? 'development'
         : 'production',
+    'process.env.__NEXT_DEV_SERVER': dev ? '1' : '',
     'process.env.NEXT_RUNTIME': isEdgeServer
       ? 'edge'
       : isNodeServer

packages/next/src/build/static-paths/app.ts

@@ -836,7 +836,7 @@ export async function buildAppStaticPaths({
   )
 
   const supportsRoutePreGeneration =
-    hadAllParamsGenerated || process.env.NODE_ENV === 'production'
+    hadAllParamsGenerated || !process.env.__NEXT_DEV_SERVER
 
   const fallbackMode = dynamicParams
     ? supportsRoutePreGeneration

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

@@ -762,7 +762,6 @@ export async function handler(
               routerServerContext
             ),
           err: getRequestMeta(req, 'invokeError'),
-          dev: routeModule.isDev,
         },
       }
 

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

@@ -197,7 +197,6 @@ async function requestHandler(
           silenceLog,
           routerServerContext
         ),
-      dev: pageRouteModule.isDev,
     },
   }
   let finalStatus = 200

packages/next/src/cli/next-build.ts

@@ -85,8 +85,8 @@ const nextBuild = async (options: NextBuildOptions, directory?: string) => {
 
   if (debugPrerender) {
     warn(
-      `Prerendering is running in debug mode. ${italic(
-        'Note: This may affect performance and should not be used for production.'
+      `Prerendering is running in debug mode with NODE_ENV='development'. ${italic(
+        'This will affect performance and should not be used for production.'
       )}`
     )
   }

packages/next/src/cli/next-dev.ts

@@ -328,6 +328,7 @@ const nextDev = async (
         env: {
           ...defaultEnv,
           ...(isTurbopack ? { TURBOPACK: process.env.TURBOPACK } : undefined),
+          __NEXT_DEV_SERVER: '1',
           NEXT_PRIVATE_START_TIME: process.env.NEXT_PRIVATE_START_TIME,
           NEXT_PRIVATE_WORKER: '1',
           NEXT_PRIVATE_TRACE_ID: traceId,