Agent skill · software engineering · vercel
runtime-debug
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.
Why this skill is useful
Adds specific debugging workflows and commands for diagnosing Next.js runtime-bundle issues that the AI wouldn't reliably generate on its own.
What it needs
About 1k tokens when loaded. Last updated 2026-08-07. 141,663 stars on the source repository.
What this skill does
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: ISWEBPACKTEST=1 forces webpack (turbopack is default), NEXTSKIPISOLATE=1 skips packing next.js. For module-resolution validation, always rerun without NEXTSKIPISOLATE=1. Stack Trace Visibility Set NEXTSHOWIGNORELISTED=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: 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
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills vercel/runtime-debug