Communitygithub.com

0n6k4v-Coder/otimizador-componentes-cache-next

Otimiza um aplicativo Next.js que possui `cacheComponents: true` — seja a estrutura estática na primeira pintura, ou a navegação interna entre rotas. Escolhe o loop de diagnóstico correspondente e o executa.

O que é otimizador-componentes-cache-next?

Este skill é projetado para desenvolvedores que trabalham com aplicativos Next.js que possuem `cacheComponents: true` habilitado. Ele oferece dois loops de diagnóstico especializados: o **loop de renderização de página** (ppr-loop), que otimiza a carga inicial de uma única rota, expandindo a estrutura estática e classificando áreas de fallback Suspense; e o **loop de navegação** (instant-nav-loop), que garante que, ao navegar entre rotas, o layout estático da rota de destino seja exibido imediatamente, sem esperar pela resolução dos dados. O skill utiliza um cookie específico (`next-instant-navigation-testing`) para congelar as escritas dinâmicas do framework, capturando a estrutura estática e os fallbacks Suspense como referência. Ele é executado como parte do ecossistema `next-dev-loop`, que fornece um navegador headless e um servidor MCP para logs. As refatorações propostas seguem um padrão de 'modo plano', exigindo uma proposta coerente antes de aplicar qualquer alteração, garantindo que decisões como extração de I/O em componentes Suspense ou uso de `'use cache'` com `cacheLife` sejam cuidadosamente pensadas. O skill enfatiza a necessidade de uma diferença visível nas capturas de tela antes e depois da otimização, rejeitando mudanças que não produzam um resultado perceptível.

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

Perguntar na sua IA favorita

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

Documentação

O que otimizador-componentes-cache-next faz?

Dois loops, alavancas e primitivas compartilhadas, diagnósticos diferentes:

  • Loop de renderização de página (ppr-loop.md) — expande a estrutura estática de uma única página. Classifica áreas de fallback Suspense em uma renderização apenas da estrutura.
  • Loop de navegação (instant-nav-loop.md) — quando o usuário clica em um link de A para B, exibe imediatamente o layout estático de B (chrome, estrutura, fallbacks com formato de conteúdo) em vez de manter a UI de A até que os dados de B sejam resolvidos. Captura os limites suspensos de B após pushstate, classifica cada um por suspended_by[].name, descarta hooks de cliente exclusivos de SSR.

Escolha um e execute-o do início ao fim.

requer

  • next-dev-loop iniciado para esta sessão — ele abre o navegador headless, expõe a CLI agent-browser e conecta o servidor MCP de desenvolvimento que fornece mcp get_logs.
  • cacheComponents: true em next.config.ts. Recuse caso contrário.

pré-voo (compartilhado)

  1. Confirme cacheComponents: true.
  2. O usuário já deve estar na página que cada loop necessita no navegador headless (do next-dev-loop) — logado, com qualquer estado configurado. Este skill não pode gerenciar autenticação, SSO ou MFA; ele assume a configuração manual como ponto de partida. (Cada sub-loop nomeia qual página espera.)
  3. agent-browser get url para fixar a rota atual.

Cada loop define o cookie instantâneo conforme necessário (veja a seção cookie instantâneo compartilhada abaixo).

cookie instantâneo (compartilhado)

Ambos os loops usam o cookie next-instant-navigation-testing para congelar as escritas de dados dinâmicos do framework. Uma vez definido, o conteúdo visível na página é a estrutura estática + fallbacks Suspense — é isso que capturamos para avaliar a otimização.

Defina-o com uma tupla de bloqueio pendente [0, "<id-único>"]. O id é qualquer string única; a convenção é um carimbo aleatório com prefixo p para que escopos concorrentes não colidam:

agent-browser cookies set next-instant-navigation-testing '[0,"p<aleatório>"]' \
  --url <origem>

O pré-voo de cada loop especifica quando defini-lo dentro do fluxo. Limpe-o no final (veja desmontagem abaixo).

decidir qual loop

  • Renderização de página quando a reclamação é sobre a carga inicial de uma rota. Leia ppr-loop.md.
  • Navegação quando é sobre navegar entre duas rotas. Leia instant-nav-loop.md.

Ambíguo → pergunte.

alavancas de refatoração compartilhadas

  • Empurrar para baixo — extraia E/S em um filho envolvido por Suspense para que o pai permaneça estático e os irmãos estáticos sejam promovidos para a estrutura.
    • Recursão, não envolva cegamente. Se um limite Suspense já envolve um componente contendo tanto conteúdo estático quanto E/S, leia dentro, extraia o JSX dependente de E/S em uma nova folha e promova os irmãos estáticos para cima.
  • Cache — 'use cache' + cacheLife(<perfil>). Sempre pergunte ao usuário sobre frescor; mapeie para um predefinido (seconds / minutes / hours / days / weeks / max / default).

Empurrar para baixo e cache se compõem: empurrar para baixo levanta a estrutura estática, cache elimina a lacuna de dados restante.

propor via modo plano (compartilhado)

Cada refatoração passa pelo modo plano antes de ser aplicada. Trate isso como um sinal: o trabalho de aplicação é engenharia agentiva não trivial, não uma edição modelada. Este skill fornece a estrutura — qual alavanca usar, qual candidato corrigir, qual é a diferença visível esperada — mas o trabalho real (qual arquivo editar, como extrair limpidamente a E/S, onde colocar o novo limite Suspense, qual perfil cacheLife perguntar ao usuário) é uma decisão de julgamento que você precisa pensar. O modo plano força uma proposta coerente antes de tocar no código e dá ao usuário a chance de redirecionar em qualquer uma dessas decisões.

saída sem estrutura (compartilhado)

As alavancas presumem que existe uma estrutura para expandir ou armazenar em cache. Se a rota for totalmente bloqueante — HTTP 500 com blocking-route ou NEXT_STATIC_GEN_BAILOUT em mcp get_logs, ou zero limites Suspense em uma página renderizada visivelmente — não há estrutura. Exiba o bloqueador estrutural e pare; o usuário deve envolver o acesso dinâmico problemático em <Suspense> antes que qualquer loop possa ajudar.

verificar requer uma diferença visível (compartilhado)

Cada loop captura uma captura de tela de linha de base da estrutura antes de aplicar qualquer alteração e depois tira outra captura de tela após. Relate ambos os caminhos no resumo final para que o usuário possa ver o que mudou. As duas capturas devem diferir visivelmente — área de fallback reduzida, conteúdo promovido para a superfície estática, fallback alvo desaparecido ou com formato de conteúdo. Capturas idênticas significam que a refatoração não funcionou; desfaça. "Compila limpo" não é o critério.

Oculte a sobreposição de desenvolvimento antes de cada captura de tela. A sobreposição de desenvolvimento do Next.js (<nextjs-portal> na raiz do documento) renderiza orientação de navegação instantânea, erros de construção e outro chrome de desenvolvimento que polui a comparação antes/depois. Oculte-a, tire a captura de tela, restaure:

agent-browser eval "document.querySelector('nextjs-portal').style.display='none'"
agent-browser screenshot <caminho>
agent-browser eval "document.querySelector('nextjs-portal').style.display=''"

antipadrões (compartilhado)

Não substitua limites Suspense granulares por um esqueleto de carregamento de nível superior. Um loading.tsx para todo o segmento, ou um <Suspense fallback={<Skeleton />}> no nível raiz (ou pior, fallback={null} que deixa a UI em branco), anula a otimização deste skill — que é extrair chrome estático real acima de cada limite granular e usar fallbacks com formato de conteúdo por região. Um substituto grosseiro "a página está carregando" ignora o trabalho completamente.

pegadinhas (compartilhado)

  • Desenvolvimento não pré-busca como produção, e as rotas compilam no primeiro acesso — então após uma navegação ou recarregamento, o DOM continua atualizando por um período notavelmente mais longo do que a experiência de produção eventual. Aguarde pacientemente o DOM estabilizar antes de capturar a árvore React ou tirar uma captura de tela — por exemplo, consulte document.documentElement.innerHTML.length até que permaneça inalterado em duas leituras consecutivas. Um atraso curto fixo corre o risco de amostrar durante a renderização.
  • Não tente verificar a pré-busca de navegação inspecionando o tráfego de rede de desenvolvimento — desenvolvimento não dispara requisições de pré-busca, então a aba de rede, chamadas manuais router.prefetch() e <Link prefetch={true}> parecerão quebrados independentemente de seu código estar correto. A receita de navegação SPA com cookie bloqueado em instant-nav-loop.md sob verificar já é a receita canônica para isso — ela simula o que a produção pré-renderizaria no RSC pré-buscado sem exigir que a pré-busca seja realmente disparada. Use-a; não invente uma alternativa de aba de rede.
  • O pipeline de diagnóstico pode ser instável — temporização de anexação do DevTools, corridas de estabilização do DOM e efeitos de compilação de desenvolvimento podem cada um produzir capturas inconsistentes de uma execução para a próxima. Quando um resultado parecer estranho (um candidato aparece que você não espera, ou um que você espera não aparece), execute o diagnóstico novamente 2–3 vezes e verifique; limites que aparecem consistentemente são reais, ocorrências únicas são ruído.

referência (primitivas compartilhadas)

agent-browser react suspense             adicione --only-dynamic para filtrar
--json                                    limites suspensos do lado do
                                          servidor. Cada entrada tem
                                          jsx_source + suspended_by[] com
                                          nomes de bloqueadores brutos
                                          (usePathname, cookies, fetch,
                                          cache, ...); classifique por nome
                                          para regras de cada loop

POST /__nextjs_original-stack-frames      corpo { frames: StackFrame[],
                                          isServer, isEdgeServer,
                                          isAppDirectory }; retorna um
                                          resultado por quadro com
                                          arquivo:linha:coluna

mcp get_logs                              ferramenta MCP de desenvolvimento
                                          do next-dev-loop; expõe
                                          blocking-route /
                                          NEXT_STATIC_GEN_BAILOUT 500s

cacheLife('<perfil>')                     default | seconds | minutes
                                          | hours | days | weeks | max

Primitivas por loop em instant-nav-loop.md.

desmontagem (compartilhado)

Exclua o cookie pelo nome — sobrescreva com um carimbo expirado:

agent-browser cookies set next-instant-navigation-testing x \
  --url <origem> --expires 1

Nunca agent-browser cookies clear (sem argumentos) — limpa a autenticação.


Irmão de next-dev-loop — inicie esse primeiro.

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

Verify Next.js runtime behavior after editing app code. Use this skill to confirm a change actually works in a running app — not just that it compiles or type-checks. Combines /_next/mcp (Next.js's view) with agent-browser (the browser's view). Requires a running `next dev`.

Habilidades Relacionadas