home / skills / vercel / next.js / runtime-debug
This skill helps diagnose runtime-bundle and module-resolution regressions by mirroring CI, tracing bundles, and validating inclusion reasons across
npx playbooks add skill vercel/next.js --skill runtime-debugReview the files below or copy the command above to add this skill to your agents.
---
name: runtime-debug
description: >
Debug and verification workflow for runtime-bundle and module-resolution
regressions. Use when diagnosing unexpected module inclusions, bundle
size regressions, or CI failures related to NEXT_SKIP_ISOLATE, nft.json
traces, or runtime bundle selection (module.compiled.js). Covers CI env
mirroring, full stack traces via __NEXT_SHOW_IGNORE_LISTED, route trace
inspection, and webpack stats diffing.
---
# 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`:
```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
This skill helps debug and verify runtime-bundle and module-resolution regressions in Next.js apps. It focuses on diagnosing unexpected module inclusions, bundle size regressions, and CI failures related to NEXT_SKIP_ISOLATE, nft.json traces, or runtime bundle selection. The workflow produces concrete proofs of inclusion and guards to prevent Node-only internals from leaking into user bundles.
Reproduce failures in an environment that mirrors CI, toggle key env vars (like IS_WEBPACK_TEST and NEXT_SKIP_ISOLATE), and collect artifacts: route trace nft.json files, emitted webpack stats, and server chunk traces. Use __NEXT_SHOW_IGNORE_LISTED to get full stack frames from the dev server. Diff webpack stats and inspect route traces to identify which module required a forbidden internal and why it was bundled.
When should I set NEXT_SKIP_ISOLATE?
Use NEXT_SKIP_ISOLATE=1 to skip packing next.js for faster experimentation, but always rerun the final validation without it to ensure module-resolution is correct.
How do I get concrete reasons why a module was included?
Emit webpack stats (config.profile = true) and call stats.toJson({ modules: true, chunks: true, reasons: true }) to see exact inclusion reasons and diff across modes.