# Next Dev Loop

> 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.

Fuente: https://skillsagentes.com/skills/vercel/next.js/next-dev-loop
Markdown: https://skillsagentes.com/skills/vercel/next.js/next-dev-loop.md

Repositorio: https://github.com/vercel/next.js
Autor: vercel
Licencia: MIT
Actualizado: hace 5 días
Coste de contexto: 69 tok instalada, 2k tok al activarse, 2k tok con todos los archivos del bundle
Bundle: 1 archivo, 8 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 next-dev-loop --agent claude-code
# Cursor
npx -y skills add vercel/next.js --skill next-dev-loop --agent cursor
# Codex
npx -y skills add vercel/next.js --skill next-dev-loop --agent codex
# Gemini CLI
npx -y skills add vercel/next.js --skill next-dev-loop --agent gemini
# Windsurf
npx -y skills add vercel/next.js --skill next-dev-loop --agent windsurf
# Cline
npx -y skills add vercel/next.js --skill next-dev-loop --agent cline
```

## Qué hace

- Verifica el comportamiento en tiempo de ejecución de Next.js después de editar el código de la aplicación
- Confirma que un cambio funciona de verdad en la app corriendo, no solo que compila o pasa los tipos
- Combina `/_next/mcp`, que es la visión de Next.js, con agent-browser, que es la del navegador
- Acota el alcance antes de editar y verifica después

## Cuándo usarla

- Se acaba de editar código de la aplicación y hay que comprobar que el cambio funciona en ejecución

## Qué la activa

- "Comprueba que este cambio funciona en la app"
- "Verifica el comportamiento en runtime de esta ruta"
- "¿Está realmente aplicándose mi cambio?"

## Antes de instalar

- Necesita un `next dev` corriendo.
- Variables de entorno: SESSION
- reads environment config

## Archivos

- SKILL.md — 8 KB

## SKILL.md

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

# next-dev-loop

The edit/verify rhythm during `next dev` — make a change, then
confirm it actually works at runtime, not only that the types or
the build are happy.

You verify through two views of the same running app:

- **`/_next/mcp`** — an HTTP endpoint Next.js exposes about itself.
  Knows framework-specific things: routes, segments, RSC, server
  actions, server logs, and errors as Next.js saw them. Call
  `tools/list` for the current surface.
- **`agent-browser`** — a CLI that drives a real Chrome. Knows
  framework-agnostic browser things: DOM, console, network, React
  fiber, vitals. Before driving it, run `agent-browser skills get core`
  once for the version-matched usage guide — don't guess subcommands
  from memory.

The two views cross-check each other.

## requires

- Next.js **16.3+** with **Turbopack** — `/_next/mcp` plus the
  proactive compile check via `get_compilation_issues`.
- `agent-browser` **>= 0.31.1** — React introspection, worktree-scoped
  `session id`, idempotent `--restore`, and launch flag reconciliation.

These are hard floors, not soft preferences. If anything is missing,
tell the user how to upgrade and stop. Don't fall back to grepping
source or to a weaker probe — this skill assumes both views are live
at the versions above.

- Upgrade Next.js: `pnpm next upgrade` (or `npx next upgrade`).
  Docs: https://nextjs.org/docs/app/getting-started/upgrading
  (version-16 guide:
  https://nextjs.org/docs/app/guides/upgrading/version-16)
- Install or upgrade `agent-browser`: `npm i -g agent-browser@latest`.
  If the CLI isn't on `PATH`, install it before continuing — preflight
  expects to invoke it directly.

## preflight

Once per session, confirm both views are live.

1. **Open `agent-browser` at the target URL, restoring saved
   login state when present.** First derive one stable session id for
   this checkout and use it for every `agent-browser` command:

   ```bash
   SESSION="$(agent-browser session id --scope worktree --prefix next-dev-loop)"
   export AGENT_BROWSER_SESSION="$SESSION"
   export AGENT_BROWSER_RESTORE="$SESSION"
   ```

   Then open the target URL:

   ```bash
   agent-browser --session "$SESSION" --restore --headed --enable react-devtools open <url>
   ```

   `--scope worktree` keeps parallel worktrees and copied checkouts
   from colliding. Bare `--restore` uses the session id as the
   persistence key, loads saved cookies/localStorage before navigation
   when present, and auto-saves state on close. Always pass the desired
   launch flags on `open`; agent-browser will reuse, relaunch, or restart
   its scoped background state as needed.

   The browser is the user's. If state was not restored (first run,
   expired session) and the page is gated, the user drives the login —
   pause until they confirm. After login, continue using the same session
   and restore context; `agent-browser close` saves the cookie state so
   the next `open` restores it.

2. Probe `/_next/mcp` (`tools/list`) — confirm it's reachable and
   lists `get_compilation_issues`. First read the port off the
   `next dev` banner; if it isn't 3000, set
   `NEXT_MCP_URL=http://localhost:<port>/_next/mcp` before probing:
   - Unreachable → either `next dev` isn't running, or Next.js is
     below 16.3. Check `package.json` to disambiguate, then refuse.
   - `get_compilation_issues` not in the list → Next.js below 16.3.
     Refuse and tell the user to upgrade.
3. `get_compilation_issues` doubles as a Turbopack probe. An error
   response of `"Turbopack project is not available..."` means the
   user is on webpack. Refuse — Turbopack is required.
4. `get_routes` → your route map for the rest of the session.

## loop

### before the edit — narrow the scope

Ask the running app, not the codebase. `/_next/mcp` knows which
files rendered the current route; use those as your search scope.
Runtime introspection stays cheap as the codebase grows; agentic
search doesn't.

### after the edit — verify

Four failure modes. Check each:

- **Compiles** — `get_compilation_issues`.
- **Runs without errors** — `/_next/mcp` (server and bubbled-up
  browser errors both surface here).
- **Behaves as intended** — `agent-browser` drives the page; assert
  what the user actually sees.
- **React-level behavior** — `agent-browser` with react-devtools
  enabled exposes the component tree, props, state, and render
  counts. Anchor framework-level checks here (extra renders,
  server/client boundary shifts, suspense fallbacks) — DOM asserts
  alone miss them.

Pick the specific tool from `tools/list` or the agent-browser
manual rather than from memory.

## gotchas

- **Every `agent-browser` command must know your session and restore
  key, or it may use an empty default browser or fail to save login
  state.** Easiest: export both `AGENT_BROWSER_SESSION="$SESSION"` and
  `AGENT_BROWSER_RESTORE="$SESSION"` at the top of each shell you run
  agent-browser in. If you do not export them, pass
  `--session "$SESSION" --restore` on every command.
- **When the two views disagree, suspect the tooling first.** If
  `agent-browser` says a route is broken but `/_next/mcp` and the
  server say it rendered cleanly, a stale or misdirected browser
  session is the likelier cause than a real bug — reconcile the views
  before debugging the app.
- Confirming a click or navigation: the page settles a beat later, so
  wait with `wait --load networkidle` (no path to get wrong), then
  snapshot/read to confirm the page. Avoid `wait --url` unless you pass
  the link's exact href — a guessed or placeholder path won't match the
  real URL and times out after 25s.
- A blank read, empty snapshot, `about:blank`, or a "no browser
  session" error — right after `open` or after a click (even if `open`
  reported the page) — is the browser dropping the page (a stale
  session), not a broken route. Reopen your session at the URL with
  `--session "$SESSION" --restore` and re-snapshot; if still blank,
  run `agent-browser --session "$SESSION" --restore close`, then open
  again. Don't fall back to `curl`; it bypasses the browser you're
  testing.
- React introspection output is stale after navigation. Re-run.
- `/_next/mcp` replies are SSE — read the JSON off the `data:` line
  with `sed -n 's/^data: //p'` (a plain `sed 's/^data: //'` leaves the
  `event:` line and the parse fails).
- `get_errors` and `get_page_metadata` need at least one navigation
  to populate.

## reference

All tools below are present once preflight passes. If `tools/list`
is missing any of them, preflight should have refused — re-check.

```
# /_next/mcp                 notes
get_project_metadata         projectPath, devServerUrl, bundler
get_routes                   fs-scan; no browser session needed
get_errors                   runtime + build; needs a browser session;
                             includes browser-side errors caught by the
                             dev server
get_page_metadata            segment trie + routerType; needs a browser
                             session; use as a discovery shortcut for
                             which files power a route
get_logs                     returns logFilePath
get_server_action_by_id      hashed id → file + functionName
get_compilation_issues       Turbopack only; errors on webpack
                             ("Turbopack project is not available")
```

## teardown

Close the session with the same session and restore context:
`agent-browser --session "$SESSION" --restore close`. `close` saves
that session's cookies and storage so the next loop's `--restore` open
keeps the user logged in. Leave `next dev` up for the next loop.

## Dónde encaja

- Categoría: [Testing y QA](https://skillsagentes.com/categorias/testing-qa.md) — Flujos de testing unitario, de integración y end-to-end.
- 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'.
- [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.
- [Sandbox Bench](https://skillsagentes.com/skills/vercel/next.js/sandbox-bench.md): Compara el rendimiento de cambios de React o Next.js en VMs de Vercel Sandbox con estadística A/B pareada: rps, latencia, p95, TTFB, RSS y bytes de documento y Flight.

## Skills relacionadas

- [Pr Status Triage](https://skillsagentes.com/skills/vercel/next.js/pr-status-triage.md): Tría fallos de CI y comentarios de revisión de PR con scripts/pr-status.js: prioriza por bloqueo (build, lint, tipos, tests), empareja variables de CI para reproducir en local y distingue flakies.
- [Router Act](https://skillsagentes.com/skills/vercel/next.js/router-act.md): Cómo escribir tests end-to-end con createRouterAct y LinkAccordion. Úsalo al escribir tests que controlan el momento de las peticiones internas de Next.js, como los prefetches.
- [Sandbox Bench](https://skillsagentes.com/skills/vercel/next.js/sandbox-bench.md): Compara el rendimiento de cambios de React o Next.js en VMs de Vercel Sandbox con estadística A/B pareada: rps, latencia, p95, TTFB, RSS y bytes de documento y Flight.
- [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.

---

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