---
name: vercel-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."
license: "MIT"
metadata:
  decimalai-skill-id: "82e19004-5467-4930-94fc-2e796e8a1bf8"
  decimalai-version-id: "94e78f94-3e72-4453-9ec0-1eef08e50155"
  decimalai-version: "1"
  decimalai-body-sha256: "1fe1bbc9a85f043b6669744825834f09f6b1dcebc330c108f3b8fca0826b1f9a"
  decimalai-name: "vercel/runtime-debug"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "coding"
  decimalai-source: "https://app.decimal.ai/s/vercel-runtime-debug@1/SKILL.md"
---
# 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