Communitygithub.com

next-dev-loop

Verifica el comportamiento en tiempo de ejecución de Next.js después de editar el código de la aplicación. Utiliza esta skill para confirmar que un cambio realmente funciona en una aplicación en ejecución, no solo que compila o verifica tipos. Combina `/_next/mcp` (la vista de Next.js) con `agent-browser` (la vista del navegador). Requiere que `next dev` esté en ejecución.

¿Qué es next-dev-loop?

La skill `next-dev-loop` está diseñada para desarrolladores que trabajan con Next.js y desean validar rápidamente los cambios en el código sin necesidad de depender únicamente de la compilación o las verificaciones de tipo. Proporciona un bucle de edición/verificación eficiente que cruza la información de dos fuentes complementarias: el endpoint interno `/_next/mcp` de Next.js (que expone información específica del framework como rutas, segmentos, errores del servidor y acciones del servidor) y la herramienta `agent-browser` (que controla un navegador Chrome real para inspeccionar el DOM, la consola, la red, el árbol de componentes React y las métricas web). La skill es compatible con versiones específicas de Next.js (16.3+ con Turbopack) y agent-browser (>= 0.31.1). Incluye una rutina de pre-vuelo que verifica que ambos componentes estén activos antes de comenzar el bucle principal, y proporciona guías detalladas para manejar sesiones persistentes del navegador, evitar errores comunes y depurar discrepancias entre las dos vistas. Es ideal para desarrolladores que buscan un flujo de trabajo de desarrollo más fiable y profundo, más allá de la compilación básica.

Compatible con~Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add https://github.com/0n6k4v-Coder/skills/tree/HEAD/next.js/next-dev-loop

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿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 a tools/list para 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, ejecuta agent-browser skills get core una 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/mcp más la verificación proactiva de compilación mediante get_compilation_issues.
  • agent-browser >= 0.31.1 — introspección de React, session id con ámbito del árbol de trabajo, --restore idempotente 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.

verificación previa

Una vez por sesión, confirma que ambas vistas están activas.

  1. Abre agent-browser en 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 de agent-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 worktree evita que los árboles de trabajo paralelos y los checkouts copiados colisionen. --restore sin 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 en open; 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 close guarda el estado de las cookies para que la próxima open lo restaure.

  2. Sonda /_next/mcp (tools/list) — confirma que es accesible y que lista get_compilation_issues:

    • Inaccesible → next dev no se está ejecutando o Next.js está por debajo de 16.3. Verifica package.json para diferenciar, luego rechaza.
    • get_compilation_issues no está en la lista → Next.js está por debajo de 16.3. Rechaza e indica al usuario que actualice.
  3. get_compilation_issues tambié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.

  4. 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-browser controla la página; verifica lo que el usuario realmente ve.
  • Comportamiento a nivel de React — agent-browser con 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-browser debe 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 tanto AGENT_BROWSER_SESSION="$SESSION" como AGENT_BROWSER_RESTORE="$SESSION" al principio de cada shell donde ejecutes agent-browser. Si no los exportas, pasa --session "$SESSION" --restore en cada comando.
  • Cuando las dos vistas no coinciden, sospecha primero de las herramientas. Si agent-browser dice que una ruta está rota pero /_next/mcp y 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. Evita wait --url a 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:blank o un error "no browser session" — justo después de open o después de un clic (incluso si open informó 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" --restore y vuelve a tomar la instantánea; si sigue en blanco, ejecuta agent-browser --session "$SESSION" --restore close y luego abre de nuevo. No recurras a curl; 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/mcp son SSE — lee el JSON de la línea data: con sed -n 's/^data: //p' (un sed 's/^data: //' simple deja la línea event: y el análisis falla).
  • Servidor de desarrollo en un puerto que no sea el 3000: lee el banner de next dev; establece NEXT_MCP_URL=http://localhost:<puerto>/_next/mcp.
  • get_errors y get_page_metadata necesitan 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.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

0n6k4v-Coder/skills

Translates Figma motion and animations into production-ready application code. Use when implementing animation/motion from a Figma design — user mentions "implement this motion", "add animation from Figma", "animate this component", provides a Figma URL whose node is animated, or when `get_design_context` returns motion data or instructs you to call `get_motion_context`.

0n6k4v-Coder/skills

Motion / animation context for the `use_figma` MCP tool — animating Figma nodes via manual keyframes, animation styles, easing, and timeline duration. Load alongside figma-use whenever a task involves adding, editing, or inspecting animation on a node.

0n6k4v-Coder/skills

Generate motion specification annotations from After Effects timeline data. Use when the user mentions "motion", "motion spec", "animation spec", "timeline", or wants to document a component's animation properties.

0n6k4v-Coder/skills

Turn on Cache Components in a Next.js app and resolve the blocking routes it surfaces. Use when the user wants to enable, adopt, or migrate to Cache Components, flip the `cacheComponents` flag, work through a flood of blocking-prerender / instant validation errors, run the `cache-components-instant-false` codemod, or decide between opting routes out with `export const instant = false` and fixing them in place.

0n6k4v-Coder/skills

Optimize a Next.js app that has `cacheComponents: true` — either the static shell on first paint, or the in-app navigation between routes. Picks the matching diagnostic loop and runs it.

Skills relacionados