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.
소스 정보
- 저장소
- vercel/next.js
- 최근 소스 활동
- 2026년 5월 14일 20:29
- 감지된 SKILL.md 언어
- 영어
- 스타
- 143,133
- 포크
- 34,589
설치 방법
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
소스 파일 검토
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
SKILL.md 표시 중
SKILL.md
소스 지침 · 읽기 전용 미리보기- name
- 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.
- metadata
- {"internal":true}
# 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
GitHub에서 보기