Communitygithub.com

next-dev-loop

Verificar o comportamento em tempo de execução do Next.js após editar o código do aplicativo. Use esta skill para confirmar que uma alteração realmente funciona em um aplicativo em execução — não apenas que compila ou passa na verificação de tipos. Combina /_next/mcp (a visão do Next.js) com agent-browser (a visão do navegador). Requer um `next dev` em execução.

O que é next-dev-loop?

next-dev-loop é uma skill profissional para agentes de IA que acelera o ciclo de edição/verificação no Next.js durante o `next dev`. Em vez de apenas garantir que o código compila ou os tipos estão corretos, ela força uma verificação real em tempo de execução através de duas perspectivas complementares: o endpoint `/ _next/mcp` do Next.js (que fornece informações detalhadas sobre rotas, segmentos, RSC, ações do servidor e erros conforme o framework os vê) e o `agent-browser` (um CLI que controla um Chrome real para inspecionar DOM, console, rede, árvore React e métricas de performance). A skill executa um pré-voo obrigatório para confirmar que ambas as ferramentas estão ativas e nas versões corretas (Next.js 16.3+ com Turbopack, agent-browser ≥ 0.31.1), estabelece uma sessão persistente do navegador com suporte a restauração de estado de login, e então guia o agente em um loop: antes da edição, restringe o escopo às informações do servidor; após a edição, verifica quatro modos de falha (compilação, execução sem erros, comportamento esperado e comportamento no nível React). A skill também documenta várias armadilhas comuns, como sessões obsoletas do navegador, indisponibilidade do endpoint MCP e a necessidade de esperar a página assentar após navegações, garantindo verificações robustas e reproduzíveis. É ideal para desenvolvedores que querem feedback de alta fidelidade sobre suas alterações no Next.js, sem depender de suposições sobre o código fonte ou de ferramentas mais fracas como `curl`.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que next-dev-loop faz?

O ritmo de edição/verificação durante next dev — faça uma alteração e depois confirme que ela realmente funciona em tempo de execução, não apenas que os tipos ou o build estão satisfeitos.

Você verifica através de duas visões do mesmo aplicativo em execução:

  • /_next/mcp — um endpoint HTTP que o Next.js expõe sobre si mesmo. Sabe coisas específicas do framework: rotas, segmentos, RSC, actions do servidor, logs do servidor e erros conforme o Next.js os viu. Chame tools/list para obter a superfície atual.
  • agent-browser — um CLI que controla um Chrome real. Sabe coisas do navegador independentes de framework: DOM, console, rede, React fiber, vitals. Antes de usá-lo, execute agent-browser skills get core uma vez para obter o guia de uso correspondente à versão — não adivinhe subcomandos de memória.

As duas visões se verificam mutuamente.

requer

  • Next.js 16.3+ com Turbopack — /_next/mcp mais a verificação proativa de compilação via get_compilation_issues.
  • agent-browser >= 0.31.1 — introspecção React, session id com escopo de worktree, --restore idempotente e reconciliação de flags de inicialização.

Estes são limites mínimos obrigatórios, não preferências opcionais. Se algo estiver faltando, diga ao usuário como atualizar e pare. Não recorra a grep no código fonte ou a uma sonda mais fraca — esta skill assume que ambas as visões estão ativas nas versões acima.

pré-voo

Uma vez por sessão, confirme que ambas as visões estão ativas.

  1. Abra o agent-browser na URL alvo, restaurando o estado de login salvo, quando presente. Primeiro, derive um session id estável para este checkout e use-o em todos os comandos agent-browser:

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

    Em seguida, abra a URL alvo:

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

    --scope worktree evita que worktrees paralelos e checkouts copiados colidam. --restore sozinho usa o session id como chave de persistência, carrega cookies/localStorage salvos antes da navegação quando presentes e salva automaticamente o estado ao fechar. Sempre passe as flags de inicialização desejadas no open; o agent-browser reutilizará, relançará ou reiniciará seu estado de fundo com escopo conforme necessário.

    O navegador é do usuário. Se o estado não foi restaurado (primeira execução, sessão expirada) e a página está protegida, o usuário faz o login — pause até que ele confirme. Após o login, continue usando a mesma sessão e contexto de restauração; agent-browser close salva o estado dos cookies para que o próximo open o restaure.

  2. Sonda /_next/mcp (tools/list) — confirme que está acessível e lista get_compilation_issues:

    • Inacessível → ou next dev não está em execução, ou o Next.js está abaixo da versão 16.3. Verifique package.json para desambiguar, depois recuse.
    • get_compilation_issues não está na lista → Next.js abaixo de 16.3. Recuse e diga ao usuário para atualizar.
  3. get_compilation_issues também serve como uma sonda do Turbopack. Uma resposta de erro "Turbopack project is not available..." significa que o usuário está no webpack. Recuse — Turbopack é obrigatório.

  4. get_routes → seu mapa de rotas para o resto da sessão.

loop

antes da edição — restrinja o escopo

Pergunte ao aplicativo em execução, não ao código fonte. /_next/mcp sabe quais arquivos renderizaram a rota atual; use-os como seu escopo de busca. A introspecção em tempo de execução permanece barata à medida que o código fonte cresce; a busca por agente não.

após a edição — verifique

Quatro modos de falha. Verifique cada um:

  • Compila — get_compilation_issues.
  • Executa sem erros — /_next/mcp (erros do servidor e erros do navegador que chegam ao servidor aparecem aqui).
  • Comporta-se como esperado — agent-browser dirige a página; afirme o que o usuário realmente vê.
  • Comportamento no nível React — agent-browser com react-devtools ativado expõe a árvore de componentes, props, estado e contagens de renderização. Fixe as verificações no nível do framework aqui (renderizações extras, mudanças de limites servidor/cliente, fallbacks de suspense) — apenas afirmações de DOM as perdem.

Escolha a ferramenta específica de tools/list ou do manual do agent-browser em vez de usar a memória.

armadilhas

  • Todo comando agent-browser precisa saber sua sessão e chave de restauração, ou pode usar um navegador padrão vazio ou falhar ao salvar o estado de login. A maneira mais fácil: exporte tanto AGENT_BROWSER_SESSION="$SESSION" quanto AGENT_BROWSER_RESTORE="$SESSION" no topo de cada shell onde você executar o agent-browser. Se não exportá-los, passe --session "$SESSION" --restore em todo comando.
  • Quando as duas visões discordam, suspeite primeiro das ferramentas. Se agent-browser diz que uma rota está quebrada mas /_next/mcp e o servidor dizem que ela renderizou corretamente, uma sessão de navegador obsoleta ou mal direcionada é a causa mais provável do que um bug real — reconcilie as visões antes de depurar o aplicativo.
  • Confirmar um clique ou navegação: a página se estabiliza um pouco depois, então espere com wait --load networkidle (nenhum caminho para errar), depois faça um snapshot/leitura para confirmar a página. Evite wait --url a menos que você passe o href exato do link — um caminho adivinhado ou placeholder não corresponderá à URL real e causará timeout após 25s.
  • Uma leitura em branco, snapshot vazio, about:blank ou um erro "no browser session" — logo após open ou após um clique (mesmo se open reportou a página) — é o navegador dropando a página (uma sessão obsoleta), não uma rota quebrada. Reabra sua sessão na URL com --session "$SESSION" --restore e faça um novo snapshot; se ainda estiver em branco, execute agent-browser --session "$SESSION" --restore close, depois abra novamente. Não recorra a curl; ele ignora o navegador que você está testando.
  • A saída da introspecção React fica obsoleta após a navegação. Execute novamente.
  • As respostas de /_next/mcp são SSE — leia o JSON da linha data: com sed -n 's/^data: //p' (um sed 's/^data: //' simples deixa a linha event: e o parse falha).
  • Servidor de desenvolvimento em porta diferente de 3000: leia o banner do next dev; defina NEXT_MCP_URL=http://localhost:<port>/_next/mcp.
  • get_errors e get_page_metadata precisam de pelo menos uma navegação para serem preenchidos.

referência

Todas as ferramentas abaixo estão presentes assim que o pré-voo passar. Se tools/list estiver faltando alguma delas, o pré-voo deveria ter recusado — verifique novamente.

# /_next/mcp                 notas
get_project_metadata         projectPath, devServerUrl, bundler
get_routes                   varredura do sistema de arquivos; nenhuma sessão de navegador necessária
get_errors                   tempo de execução + build; precisa de uma sessão de navegador;
                             inclui erros do lado do navegador capturados pelo servidor
get_page_metadata            segment trie + routerType; precisa de uma sessão de
                             navegador; use como atalho de descoberta para saber
                             quais arquivos alimentam uma rota
get_logs                     retorna logFilePath
get_server_action_by_id      id com hash → arquivo + nome da função
get_compilation_issues       apenas Turbopack; erros no webpack
                             ("Turbopack project is not available")

desmontagem

Feche a sessão com a mesma sessão e contexto de restauração: agent-browser --session "$SESSION" --restore close. close salva os cookies e armazenamento daquela sessão para que o próximo --restore open mantenha o usuário logado. Deixe next dev rodando para o próximo loop.


Skills irmãs next-dev-loop-<tópico> (por exemplo, next-dev-loop-rsc, next-dev-loop-debug) assumem que este pré-voo já foi executado; elas continuam a partir do loop.

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.

Habilidades Relacionadas