# Runtime Debug

> Flujo de depuración y verificación de regresiones de bundle de runtime y resolución de módulos: espejo del entorno de CI, trazas completas, inspección de trazas de ruta y diff de estadísticas.

Fuente: https://skillsagentes.com/skills/vercel/next.js/runtime-debug
Markdown: https://skillsagentes.com/skills/vercel/next.js/runtime-debug.md

Repositorio: https://github.com/vercel/next.js
Autor: vercel
Licencia: MIT
Actualizado: hace 3 meses
Coste de contexto: 99 tok instalada, 617 tok al activarse, 617 tok con todos los archivos del bundle
Bundle: 1 archivo, 2 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add vercel/next.js --skill runtime-debug --agent claude-code
# Cursor
npx -y skills add vercel/next.js --skill runtime-debug --agent cursor
# Codex
npx -y skills add vercel/next.js --skill runtime-debug --agent codex
# Gemini CLI
npx -y skills add vercel/next.js --skill runtime-debug --agent gemini
# Windsurf
npx -y skills add vercel/next.js --skill runtime-debug --agent windsurf
# Cline
npx -y skills add vercel/next.js --skill runtime-debug --agent cline
```

## Qué hace

- Flujo de depuración y verificación para regresiones de bundle de runtime y de resolución de módulos
- Explica cómo espejar el entorno de CI para reproducir en local
- Muestra las trazas de pila completas con `__NEXT_SHOW_IGNORE_LISTED`
- Inspecciona las trazas de ruta y compara estadísticas de webpack para probar qué se incluyó
- Sirve de guardarraíl contra regresiones en el bundle del usuario

## Cuándo usarla

- Diagnosticar inclusiones de módulo inesperadas o regresiones de tamaño de bundle
- Fallos de CI relacionados con `NEXT_SKIP_ISOLATE`, trazas `nft.json` o la selección del bundle de runtime

## Qué la activa

- "¿Por qué ha crecido el bundle?"
- "Este módulo no debería estar en el bundle"
- "Reproduce este fallo de CI en local"

## Antes de instalar

- Es un skill interno del repositorio de Next.js.

## Archivos

- SKILL.md — 2 KB

## SKILL.md

Reproducido tal cual desde vercel/next.js bajo MIT. Esta sección es el documento original y está en inglés.

# 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

## Dónde encaja

- Categoría: [Herramientas para desarrolladores](https://skillsagentes.com/categorias/herramientas-desarrollo.md) — Skills que cambian cómo tu agente escribe, revisa y despliega código.
- Creador: [vercel](https://skillsagentes.com/creators/vercel.md) — 36 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Next Cache Components Adoption](https://skillsagentes.com/skills/vercel/next.js/next-cache-components-adoption.md): Activa Cache Components en una app de Next.js y resuelve las rutas bloqueantes que aparecen. Úsalo para adoptar o migrar, activar el flag cacheComponents o decidir entre excluir rutas y arreglarlas.
- [Next Cache Components Optimizer](https://skillsagentes.com/skills/vercel/next.js/next-cache-components-optimizer.md): Lleva una ruta de Next.js a navegación instantánea bajo Cache Components o PPR mediante un bucle agéntico: codifica el objetivo como un e2e instant() en rojo y lo trabaja hasta verde, ruta a ruta.
- [Next Partial Prefetching Adoption](https://skillsagentes.com/skills/vercel/next.js/next-partial-prefetching-adoption.md): Activa Partial Prefetching en una app de Next.js y resuelve las insights que surgen: audita los Link con prefetch, activa partialPrefetching y opta por rutas con prefetch = 'partial'.
- [Next Dev Loop](https://skillsagentes.com/skills/vercel/next.js/next-dev-loop.md): Verifica el comportamiento en runtime de Next.js tras editar código de la aplicación. Combina /_next/mcp, la visión de Next.js, con agent-browser, la del navegador. Requiere un next dev en marcha.
- [Gh Stack](https://skillsagentes.com/skills/vercel/next.js/gh-stack.md): Gestiona PRs apilados y parte el trabajo en ramas revisables con gh-stack: creación, visualización, edición, push, envío, sincronización, rebase, merge y checkout.

## Skills relacionadas

- [Authoring Skills](https://skillsagentes.com/skills/vercel/next.js/authoring-skills.md): Cómo crear y mantener skills de agente en .agents/skills/. Úsalo al crear un SKILL.md, escribir descripciones, elegir campos de frontmatter o decidir qué va en un skill y qué en AGENTS.md.
- [Backport Pr](https://skillsagentes.com/skills/vercel/next.js/backport-pr.md): Lleva un pull request fusionado de Next.js desde canary a una rama de release anterior como next-16-2: localiza el commit, crea la rama, hace cherry-pick, valida y abre el PR.
- [Create Pr](https://skillsagentes.com/skills/vercel/next.js/create-pr.md): Crea ramas, commits, pushes y pull requests de GitHub para Next.js. Cubre la plantilla de PR, el formato de --body, las ramas codex/ y las directivas de git de la app Codex.
- [Dce Edge](https://skillsagentes.com/skills/vercel/next.js/dce-edge.md): Patrones de require() seguros para eliminación de código muerto y restricciones del runtime edge. Úsalo al escribir require condicionales, proteger imports de Node o editar define-env-plugin.ts.
- [Flags](https://skillsagentes.com/skills/vercel/next.js/flags.md): Cómo añadir o modificar flags experimentales de Next.js de principio a fin: tipo, esquema zod, inyección en build, paso de variables en runtime y elección entre ramificar o generar variantes.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)