runtime-debug

Original：🇺🇸 English

Translated

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.

2installs

Sourcevercel/next.js

Added on2026-02-18

NPX Install

npx skill4agent add vercel/next.js runtime-debug

SKILL.md Content

View Translation Comparison →

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:

Inspect route trace artifacts (
```
.next/server/.../page.js.nft.json
```
).

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

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

,

node:stream/promises

).

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