runtime-debug

Name: runtime-debug
Author: vercel

141kstars31kforks

How to install runtime-debug?

vercel/next.js/runtime-debug

$npx -y skills add vercel/next.js --skill runtime-debug

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Runtime Debug
2
3	Use this skill when reproducing runtime-bundle, module-resolution, or user-bundle inclusion regressions.
4
5	## Local Repro Discipline
6
7	- Mirror CI env vars when reproducing CI failures.
8	- Key variables: `IS_WEBPACK_TEST=1` forces webpack (turbopack is default), `NEXT_SKIP_ISOLATE=1` skips packing next.js.
9	- For module-resolution validation, always rerun without `NEXT_SKIP_ISOLATE=1`.
10
11	## Stack Trace Visibility
12
13	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`.
14
15	## User-Bundle Regression Guardrail
16
17	When user `next build` starts bundling internal Node-only helpers unexpectedly:
18
19	1. Inspect route trace artifacts (`.next/server/.../page.js.nft.json`).
20	2. Inspect traced server chunks for forbidden internals (e.g. `next/dist/server/stream-utils/node-stream-helpers.js`, `node:stream/promises`).
21	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).
22
23	## Bundle Tracing / Inclusion Proof
24
25	To prove what user bundling includes, emit webpack stats from the app's `next.config.js`:
26
27	```js
28	// next.config.js
29	module.exports = {
30	webpack(config) {
31	config.profile = true
32	return config
33	},
34	}
35	```
36
37	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.
38
39	## Related Skills
40
41	- `$flags` - flag wiring (config/schema/define-env/runtime env)
42	- `$dce-edge` - DCE-safe require patterns and edge constraints
43	- `$react-vendoring` - entry-base boundaries and vendored React

People who liked this also viewed

6 picks

Type

runtime-debug

141kstars31kforks

View on GitHub

How to install runtime-debug?

vercel/next.js/runtime-debug

$npx -y skills add vercel/next.js --skill runtime-debug

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Runtime Debug
2
3	Use this skill when reproducing runtime-bundle, module-resolution, or user-bundle inclusion regressions.
4
5	## Local Repro Discipline
6
7	- Mirror CI env vars when reproducing CI failures.
8	- Key variables: `IS_WEBPACK_TEST=1` forces webpack (turbopack is default), `NEXT_SKIP_ISOLATE=1` skips packing next.js.
9	- For module-resolution validation, always rerun without `NEXT_SKIP_ISOLATE=1`.
10
11	## Stack Trace Visibility
12
13	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`.
14
15	## User-Bundle Regression Guardrail
16
17	When user `next build` starts bundling internal Node-only helpers unexpectedly:
18
19	1. Inspect route trace artifacts (`.next/server/.../page.js.nft.json`).
20	2. Inspect traced server chunks for forbidden internals (e.g. `next/dist/server/stream-utils/node-stream-helpers.js`, `node:stream/promises`).
21	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).
22
23	## Bundle Tracing / Inclusion Proof
24
25	To prove what user bundling includes, emit webpack stats from the app's `next.config.js`:
26
27	```js
28	// next.config.js
29	module.exports = {
30	webpack(config) {
31	config.profile = true
32	return config
33	},
34	}
35	```
36
37	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.
38
39	## Related Skills
40
41	- `$flags` - flag wiring (config/schema/define-env/runtime env)
42	- `$dce-edge` - DCE-safe require patterns and edge constraints
43	- `$react-vendoring` - entry-base boundaries and vendored React

People who liked this also viewed

6 picks

Type