¿Qué hace next-dev-loop?
El ritmo de edición/verificación durante next dev: haz un cambio y luego
confirma que realmente funciona en tiempo de ejecución, no solo que los tipos o
la compilación estén correctos.
Verificas a través de dos vistas de la misma aplicación en ejecución:
/_next/mcp— un endpoint HTTP que Next.js expone sobre sí mismo. Conoce cosas específicas del framework: rutas, segmentos, RSC, acciones del servidor, registros del servidor y errores tal como los ve Next.js. Llama atools/listpara la superficie actual.agent-browser— una CLI que controla un Chrome real. Conoce cosas del navegador independientes del framework: DOM, consola, red, árbol de componentes React, métricas web. Antes de usarlo, ejecutaagent-browser skills get coreuna vez para obtener la guía de uso acorde a la versión — no adivines los subcomandos de memoria.
Las dos vistas se verifican mutuamente.
requisitos
- Next.js 16.3+ con Turbopack —
/_next/mcpmás la verificación proactiva de compilación medianteget_compilation_issues. agent-browser>= 0.31.1 — introspección de React,session idcon ámbito del árbol de trabajo,--restoreidempotente y reconciliación de banderas de lanzamiento.
Estos son mínimos estrictos, no preferencias suaves. Si falta algo, indica al usuario cómo actualizar y detente. No recurras a buscar en el código fuente ni a una sonda más débil — esta skill asume que ambas vistas están activas con las versiones anteriores.
- Actualizar Next.js:
pnpm next upgrade(onpx next upgrade). Documentación: https://nextjs.org/docs/app/getting-started/upgrading (guía de la versión 16: https://nextjs.org/docs/app/guides/upgrading/version-16) - Instalar o actualizar
agent-browser:npm i -g agent-browser@latest. Si la CLI no está en elPATH, instálala antes de continuar — la verificación previa espera poder invocarla directamente.
verificación previa
Una vez por sesión, confirma que ambas vistas están activas.
-
Abre
agent-browseren la URL de destino, restaurando el estado de inicio de sesión guardado cuando exista. Primero, deriva un id de sesión estable para este check-out y úsalo para cada comando deagent-browser:SESSION="$(agent-browser session id --scope worktree --prefix next-dev-loop)" export AGENT_BROWSER_SESSION="$SESSION" export AGENT_BROWSER_RESTORE="$SESSION"Luego, abre la URL de destino:
agent-browser --session "$SESSION" --restore --headed --enable react-devtools open <url>--scope worktreeevita que los árboles de trabajo paralelos y los checkouts copiados colisionen.--restoresin más usa el id de sesión como clave de persistencia, carga las cookies y el almacenamiento local guardados antes de la navegación cuando existen, y guarda automáticamente el estado al cerrar. Siempre pasa las banderas de lanzamiento deseadas enopen; agent-browser reutilizará, relanzará o reiniciará su estado de fondo con ámbito según sea necesario.El navegador es del usuario. Si el estado no se restauró (primera ejecución, sesión caducada) y la página está protegida, el usuario inicia sesión — pausa hasta que confirme. Después del inicio de sesión, continúa usando la misma sesión y contexto de restauración;
agent-browser closeguarda el estado de las cookies para que la próximaopenlo restaure. -
Sonda
/_next/mcp(tools/list) — confirma que es accesible y que listaget_compilation_issues:- Inaccesible →
next devno se está ejecutando o Next.js está por debajo de 16.3. Verificapackage.jsonpara diferenciar, luego rechaza. get_compilation_issuesno está en la lista → Next.js está por debajo de 16.3. Rechaza e indica al usuario que actualice.
- Inaccesible →
-
get_compilation_issuestambién sirve como sonda de Turbopack. Una respuesta de error como"Turbopack project is not available..."significa que el usuario está en webpack. Rechaza — Turbopack es obligatorio. -
get_routes→ tu mapa de rutas para el resto de la sesión.
bucle
antes de la edición — reduce el alcance
Pregunta a la aplicación en ejecución, no al código fuente. /_next/mcp sabe qué
archivos renderizaron la ruta actual; úsalos como tu ámbito de búsqueda.
La introspección en tiempo de ejecución sigue siendo económica a medida que
crece la base de código; la búsqueda agéntica no.
después de la edición — verifica
Cuatro modos de fallo. Verifica cada uno:
- Compila —
get_compilation_issues. - Se ejecuta sin errores —
/_next/mcp(los errores del servidor y los errores del navegador que se propagan aparecen aquí). - Se comporta como se espera —
agent-browsercontrola la página; verifica lo que el usuario realmente ve. - Comportamiento a nivel de React —
agent-browsercon react-devtools habilitado expone el árbol de componentes, las propiedades, el estado y los contadores de renderizado. Ancla las verificaciones a nivel del framework aquí (renderizados adicionales, cambios en el límite servidor/cliente, fallbacks de suspense) — las aserciones solo del DOM no los detectan.
Elige la herramienta específica de tools/list o del manual de agent-browser
en lugar de hacerlo de memoria.
gelos que hay que tener en cuenta
- Cada comando de
agent-browserdebe conocer tu sesión y clave de restauración, o podría usar un navegador predeterminado vacío o no guardar el estado de inicio de sesión. Lo más fácil: exporta tantoAGENT_BROWSER_SESSION="$SESSION"comoAGENT_BROWSER_RESTORE="$SESSION"al principio de cada shell donde ejecutes agent-browser. Si no los exportas, pasa--session "$SESSION" --restoreen cada comando. - Cuando las dos vistas no coinciden, sospecha primero de las herramientas.
Si
agent-browserdice que una ruta está rota pero/_next/mcpy el servidor dicen que se renderizó correctamente, es más probable que la causa sea una sesión del navegador obsoleta o mal dirigida que un error real — reconcilia las vistas antes de depurar la aplicación. - Confirmar un clic o una navegación: la página se estabiliza un momento
después, así que espera con
wait --load networkidle(sin ruta que pueda estar mal), luego toma una instantánea/lee para confirmar la página. Evitawait --urla menos que pases el href exacto del enlace; una ruta adivinada o un marcador de posición no coincidirá con la URL real y se agotará el tiempo de espera después de 25 s. - Una lectura en blanco, una instantánea vacía,
about:blanko un error "no browser session" — justo después deopeno después de un clic (incluso siopeninformó la página) — significa que el navegador ha descartado la página (una sesión obsoleta), no una ruta rota. Vuelve a abrir tu sesión en la URL con--session "$SESSION" --restorey vuelve a tomar la instantánea; si sigue en blanco, ejecutaagent-browser --session "$SESSION" --restore closey luego abre de nuevo. No recurras acurl; evita el navegador que estás probando. - La salida de la introspección de React está obsoleta después de la navegación. Vuelve a ejecutarla.
- Las respuestas de
/_next/mcpson SSE — lee el JSON de la líneadata:consed -n 's/^data: //p'(unsed 's/^data: //'simple deja la líneaevent:y el análisis falla). - Servidor de desarrollo en un puerto que no sea el 3000: lee el banner de
next dev; estableceNEXT_MCP_URL=http://localhost:<puerto>/_next/mcp. get_errorsyget_page_metadatanecesitan al menos una navegación para poblarse.
referencia
Todas las herramientas siguientes están presentes una vez que la verificación
previa pasa. Si falta alguna en tools/list, la verificación previa debería
haberla rechazado — vuelve a comprobar.
# /_next/mcp notas
get_project_metadata projectPath, devServerUrl, bundler
get_routes escaneo del sistema de archivos; no necesita sesión del navegador
get_errors errores en tiempo de ejecución y compilación; necesita una sesión del navegador;
incluye errores del lado del navegador capturados por el servidor de desarrollo
get_page_metadata árbol de segmentos + routerType; necesita una sesión del
navegador; úsalo como un atajo de descubrimiento para
saber qué archivos alimentan una ruta
get_logs devuelve logFilePath
get_server_action_by_id id hasheado → archivo + functionName
get_compilation_issues solo Turbopack; genera error en webpack
("Turbopack project is not available")
cierre
Cierra la sesión con el mismo contexto de sesión y restauración:
agent-browser --session "$SESSION" --restore close. close guarda
las cookies y el almacenamiento de esa sesión para que la próxima --restore open
mantenga la sesión del usuario. Deja next dev en ejecución para el siguiente bucle.
Los hermanos next-dev-loop-<tema> (p. ej., next-dev-loop-rsc, next-dev-loop-debug)
asumen que esta verificación previa ya se ejecutó; continúan desde el bucle.