Runtime Debug

Use this skill when reproducing runtime-bundle, module-resolution, or user-bundle inclusion regressions.

Local Repro Discipline

• Mirror CI env vars when reproducing CI failures.
• Key variables:

  IS_WEBPACK_TEST=1

  forces webpack (turbopack is default),

  NEXT_SKIP_ISOLATE=1

  skips packing next.js.
• For module-resolution validation, always rerun without

  NEXT_SKIP_ISOLATE=1

  .

Stack Trace Visibility

Set

__NEXT_SHOW_IGNORE_LISTED=true

to disable the ignore-list filtering in dev server error output. By default, Next.js collapses internal frames to

at ignore-listed frames

, which hides useful context when debugging framework internals. Defined in

packages/next/src/server/patch-error-inspect.ts

.

User-Bundle Regression Guardrail

When user

next build

starts bundling internal Node-only helpers unexpectedly:

1. Inspect route trace artifacts (

   .next/server/.../page.js.nft.json

   ).
2. Inspect traced server chunks for forbidden internals (e.g.

   next/dist/server/stream-utils/node-stream-helpers.js

   ,

   node:stream/promises

   ).
3. Add a

   test-start-webpack

   assertion that reads the route trace and traced server chunks, and fails on forbidden internals. This validates user-project bundling (not publish-time runtime bundling).

Bundle Tracing / Inclusion Proof

To prove what user bundling includes, emit webpack stats from the app's

next.config.js

:

// next.config.js
module.exports = {
  webpack(config) {
    config.profile = true
    return config
  },
}

Then use

stats.toJson({ modules: true, chunks: true, reasons: true })

and diff

webpack-stats-server.json

between modes. This gives concrete inclusion reasons (e.g. which module required

node:stream/promises

) and is more reliable than analyzer HTML alone.

Related Skills

• $flags

  - flag wiring (config/schema/define-env/runtime env)

• $dce-edge

  - DCE-safe require patterns and edge constraints

• $react-vendoring

  - entry-base boundaries and vendored React