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 porsuspended_by[].name, descarta hooks de cliente exclusivos de SSR.
Escolha um e execute-o do início ao fim.
requer
next-dev-loopiniciado para esta sessão — ele abre o navegador headless, expõe a CLIagent-browsere conecta o servidor MCP de desenvolvimento que fornecemcp get_logs.cacheComponents: trueemnext.config.ts. Recuse caso contrário.
pré-voo (compartilhado)
- Confirme
cacheComponents: true. - 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.) agent-browser get urlpara 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.lengthaté 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 sobverificarjá é 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.