Index of every page on this site: llms.txt
All skills
vercel avatar

/runtime-debug

@495cbfa official
by vercelvercel/next.js144k stars
32,812
Run it yourself

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.

  • 1 file
  • 2.4 KB
  • Updated 6 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/vercel/next.js/runtime-debug

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈103 tokens for metadata: the name and description. ≈497 when used: this file.

Description uses 5.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈413 characters, or 5.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 495cbfa. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 6 months ago
metadata
{
  "internal": true
}

README badge

README badge for vercel/next.js/runtime-debug