O que next-cache-components-adoption faz?
Habilite os Cache Components em um aplicativo e leve-o até uma compilação bem-sucedida. Esta skill sequencia o trabalho; as receitas para cada erro estão nos cartões de correção do overlay de desenvolvimento e na saída do terminal da compilação. O guia de migração para Cache Components é a referência canônica para os conceitos e receitas por API que esta skill aplica — consulte-o sempre que os passos da skill referenciarem um padrão ("use cache", cacheLife, posicionamento de <Suspense>, etc.) e você quiser a explicação completa.
requisitos
-
Projeto App Router. Cache Components é um recurso do App Router;
cacheComponents: truenão faz nada para rotaspages/. Se o projeto tiver uma árvorepages/ousrc/pages/mas nenhuma árvoreapp/ousrc/app/, pare e informe o usuário — a migração de Pages para App é um projeto separado, não faz parte desta skill. Um aplicativo híbrido (compages/eapp/) é aceitável: a flag afeta as rotasapp/; as rotaspages/não são afetadas e não precisam de exclusões. -
Next.js 16.3 ou posterior. Essa versão é onde os recursos dos quais esta skill depende são implementados:
cacheComponentsde nível superior,export const instant, os avisos de validação de navegação instantânea no overlay de desenvolvimento e o codemodcache-components-instant-false. Senext --versionmostrar uma versão inferior a 16.3, atualize primeiro:npx @next/codemod@latest upgrade latestpara aplicar os codemods de versão para versão.- Leia o guia de atualização de versão relevante (por exemplo, Versão 16) para o que o codemod não cobre.
-
Nenhuma chave de configuração incompatível.
cacheComponents: truegera erro em qualquer arquivo que ainda exportedynamic,revalidateoufetchCache. Traduza, não exclua. Cada exportação codifica um comportamento que a rota precisa continuar tendo; migre cada uma para seu equivalente em Cache Components através das seções por chave do guia de migração. Se um valor não puder ser traduzido de forma limpa ainda, deixe um comentário// TODO: Cache Components adoption — restore revalidate = 3600para que o loop o pegue. O codemodcache-components-instant-falsenão toca nesses. -
experimental.dynamicIOé fatal. Foi renomeado paracacheComponentsde nível superior e a chave antiga agora aborta antes que qualquer compilação possa ser executada — remova-a (ou substitua porcacheComponents: true) primeiro.experimental.useCacheainda é aceito como um alias obsoleto; redundante uma vez quecacheComponents: trueestá definido, então remova-o para maior clareza.
notas
-
Nenhuma linha de base de sucesso antes da flag. Se o aplicativo já usa
"use cache", a compilação antes da flag gera erro complease enable the feature flag cacheComponents. Habilitar a flag é a primeira coisa que você faz (no Incremental, antes do codemod; no Direto, antes de corrigir as rotas) — não é algo a ser feito após obter uma compilação bem-sucedida. Observe isso em seu resumo inicial para que não pareça uma regressão. -
Documentação offline. Cópias offline dos links do guia estão em
node_modules/next/dist/docs/, com a estrutura de diretórios numerada para ordenação (por exemplo,node_modules/next/dist/docs/01-app/02-guides/migrating-to-cache-components.md). O nome do arquivo final corresponde ao slug. Se você não conseguir prever o prefixo numerado,find node_modules/next/dist/docs -name '<slug>.md'o resolve. As páginas de erro/docs/messages/*não são incluídas no pacote. Se a documentação offline estiver totalmente ausente, executenpx @next/codemod@latest agents-mdpara escrever um índice correspondente à versão emAGENTS.md/CLAUDE.md.
a forma do trabalho
Há um loop: percorra a árvore de rotas de cima para baixo, um recurso de cada vez, adotando cada rota com next dev + um navegador. A compilação é uma verificação final para cada recurso, não a superfície de trabalho.
A escolha no passo 1 é silenciar os erros de validação primeiro ou corrigi-los conforme avança. De qualquer forma, o loop é o mesmo:
- Com uma pré-etapa silenciosa (Incremental). Execute o codemod para desativar a validação de todas as páginas e layouts. Depois de corrigir também o que o codemod não pode (chamadas de E/S síncrona, exports
revalidate/dynamic/fetchCacherestantes), a compilação passa; você envia isso como seu próprio PR e então inicia o loop — removendo uma exclusão de cada vez e adotando essa rota. Divide o trabalho em pequenos PRs revisáveis. - Sem (Direto). Habilite
cacheComponentse inicie o loop no que a compilação sinalizar primeiro. Mesmo loop, mas cada correção fica em um único branch até que a adoção esteja completa.
Em ambos, a barra de sucesso por rota é a mesma: o loop de desenvolvimento não relata erros E next build passa. Verifique com o usuário após cada recurso. Espere passar a maior parte do tempo no loop, não na pré-etapa.
contexto
cacheComponents: true exige que cada rota seja pré-renderizável. Uma rota que lê dados em tempo de requisição fora de <Suspense> é "bloqueante" e falha na compilação. export const instant = false marca uma rota como permitida para bloquear, o que a limpa tanto no desenvolvimento quanto na compilação; em um layout, cobre toda a subárvore abaixo dele. Leituras encapsuladas em uma função "use cache" contam como limites de cache, não como leituras bloqueantes.
Três classes de bloqueadores afetam os agentes nesta ordem:
- Leituras em tempo de requisição (
cookies(),headers(),await params,await searchParams). Todos os quatro bloqueiam quando usados comawaitno topo de uma página ou layout.paramsesearchParamsmuitas vezes são esquecidos porque não são enquadrados como "dados de requisição" da mesma forma que cookies e headers. A correção é mover a leitura para um filho encapsulado em<Suspense>— e paraparams/searchParams, encaminhe a promise para o filho e useawaitlá; não useawaitno topo da página. - E/S síncrona em tempo de módulo/renderização (
new Date(),Date.now(),Math.random(),crypto.randomUUID()). Elas falham na compilação mesmo cominstant = false— a exclusão não as suprime. Se estiverem em um layout compartilhado, bloqueiam todas as rotas abaixo dele. O codemod não pode corrigi-las; você precisa traduzir cada uma (armazená-la em cache com"use cache"se for estável, ou encapsulá-la emawait connection()+<Suspense>se for por requisição) antes que a compilação possa passar. Pesquise em todo o repositório por essas chamadas antes de executar qualquer outra coisa. - Arquivos
"use cache"que leem dados de requisição. Um arquivo com uma diretiva"use cache"de nível superior não pode exportarinstant; combinar os dois gera erro comOnly async functions are allowed to be exported in a "use cache" file.e significa que a diretiva estava errada para aquela rota. Remova-a antes de executar o codemod.
superfícies de trabalho
encontrando rotas bloqueantes
Prefira next dev a next build enquanto trabalha.
next dev— a superfície de trabalho. Visite uma rota; seus erros de bloqueio aparecem no overlay de desenvolvimento com stack traces completos e cartões de correção vinculando a documentação por erro. Trabalhe uma rota de cada vez — os erros não se acumulam em um só lugar. A própria rota ainda retorna HTTP 200, então leia o overlay (ou.next-dev.log), não os códigos de status. Um overlay limpo é metade de uma rota limpa — a outra metade é a verificação no navegador (consulte passo 2) e uma compilação bem-sucedida para essa rota.next build— apenas detecção. A compilação é a verificação autoritativa donext dev, não seu substituto. Use-a como a última barreira em cada recurso no loop (uma compilação bem-sucedida faz parte da barra de sucesso por rota) e como a verificação final em todo o aplicativo. No Incremental, a compilação também confirma a pré-etapa (codemod desativou todas as rotas, nenhum layout compartilhado ainda tem um bloqueador de E/S síncrona) antes de você enviar esse PR. Não recorra à compilação em vez do loop de desenvolvimento enquanto estiver trabalhando em uma rota — um erro de compilação limpo não informa o que acabou no shell estático versus o que foi transmitido. Por padrão, a compilação para na primeira rota bloqueante, portanto, também é ruim para dimensionar o trabalho. Duas flags ajudam ao iterar:--debug-build-pathscompila apenas as rotas que você nomeia (padrões glob separados por vírgula de caminhos de arquivo relativos à raiz do projeto, por exemplo,--debug-build-paths="app/admin/**/page.tsx"— não caminhos de URL;--debug-build-paths="app/(marketing)/about/page.tsx"— não/about;--debug-build-paths="app/admin"não corresponde a nada e compila silenciosamente zero rotas), e--debug-prerenderdesabilita a saída antecipada para que a compilação continue após a primeira falha de pré-renderização, relate todas as rotas bloqueantes e imprima um stack trace mais completo que nomeia o arquivo e a linha de origem.
Cada erro de bloqueio tem uma página de documentação — abra-a. Tanto o overlay de desenvolvimento quanto o terminal de compilação imprimem um link https://nextjs.org/docs/messages/<slug> com cada erro. Essa página é a receita canônica para a correção; a mensagem inline é um resumo. Busque o link para cada erro distinto que encontrar, mesmo se você achar que conhece o padrão — as receitas evoluem, e a mesma classe de erro pode ter correções diferentes dependendo do que a rota lê. Não improvise apenas com a mensagem inline. (As páginas /docs/messages/* não são incluídas offline; se você não tiver rede, recorra aos guias por API em node_modules/next/dist/docs/ e observe a limitação ao relatar.)
verificando cada correção em tempo de execução
Uma compilação bem-sucedida ou um overlay limpo não prova que a rota realmente se comporta — Cache Components é uma preocupação de tempo de execução (um shell estático com dados transmitidos). Verifique após cada correção, não apenas no final.
Em ordem de preferência:
-
next-dev-loop— fortemente preferido. Verifica cruzadamente/_next/mcpcom o navegador ao vivo viaagent-browsere expõe problemas de compilação e tempo de execução em uma única passada. Os diagnósticos (árvore React, limites de suspense, console + rede) são mais ricos do que cutucarnext devmanualmente.Instale-o antes de iniciar o loop. Não espere até encontrar algo que
next devsozinho não pode explicar. Execute:npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loopA skill requer
agent-browser >= 0.27.0e o guiará através dela.Requer Turbopack. Se o script
devempackage.jsonpassar--webpack, sinalize ao usuário e pergunte se há um motivo para permanecer no webpack. Caso contrário, mude para Turbopack (o padrão do Next.js 16.3+). Se eles quiserem manter o webpack, pule esta instalação e use o loop apenas de compilação.Você não precisa de permissão para instalar
next-dev-loopem si. É uma ferramenta, como instalar uma dependência de desenvolvimento. Se um usuário estiver na linha, informe brevemente que você está instalando para verificação. Em uma execução não interativa (CI, painel, sandbox), instale sem perguntar — "não é possível solicitar ao usuário" não é motivo para pular. A única omissão legítima é um bloqueio técnico real: sem rede, sem npm, sistema de arquivos somente leitura, uma política declarada de não novas dependências ou um script de desenvolvimento apenas com webpack. Se você pular, nomeie o bloqueador específico em seu relatório final. -
Um navegador que você pode dirigir sozinho. Playwright,
agent-browserdiretamente, qualquer ferramenta de automação de navegador. Use apenas quandonext-dev-loopestiver genuinamente bloqueado. Você perderá as verificações do lado do framework (/_next/mcp), portanto, asserções de DOM sozinhas não capturam todas as regressões — seja mais cauteloso sobre o que você chama de "verificado". -
Apenas compilação. Se você não conseguir executar um servidor de desenvolvimento, a compilação é seu único sinal. Rotas
○ (Static)sem<Suspense>são totalmente verificadas pela compilação (nada transmitido para testar). Rotas◐ (Partial Prerender)são apenas verificadas no shell — sinalize-as quando você relatar. -
Nenhuma ferramenta. Peça ao usuário para executar o servidor de desenvolvimento (ou compilação) e relatar o que veem, ou faça commit do marco que você alcançou e passe adiante.
passo 1: escolha uma estratégia
Pergunte ao usuário. Formule como uma pergunta sobre a forma dos PRs, não sobre dimensionamento. Nunca use os rótulos internos (Incremental, Direto, marco A) ao falar com o usuário — esses são seu próprio arcabouço. Pergunte em termos de PRs e recursos, por exemplo: "Você quer que eu primeiro abra um PR que ative os Cache Components e desative a validação de todas as rotas, e depois lide com as adoções reais de rotas recurso por recurso em PRs de acompanhamento? Ou fazer tudo em um único branch?" Mesmo em um aplicativo minúsculo, o caminho incremental ainda tem valor (PR de tamanho revisável, reversível, os marcadores // TODO: Cache Components adoption funcionam como sua fila de trabalho para a próxima sessão). Não escolha por eles.
Se não houver usuário para perguntar, o padrão é Incremental e documente a escolha.
- Incremental — pré-etapa silenciosa + o loop. Execute o codemod para desativar a validação de todas as páginas e layouts, faça a compilação passar, pare e verifique com o usuário (consulte final da pré-etapa), então entre no loop do passo 2 e envie cada recurso como um PR de acompanhamento.
- Direto — pule a pré-etapa. Habilite
cacheComponentse vá direto para o loop do passo 2; as rotas bloqueantes da compilação são a fila de trabalho.
incremental
Antes de invocar o codemod, corrija as duas classes de bloqueadores que ele não pode.
-
E/S síncrona em tempo de módulo/renderização. Pesquise em todo o repositório por
new Date(),Date.now(),Math.random()ecrypto.randomUUID()(não apenasapp/**/layout.{js,jsx,ts,tsx}— a leitura pode estar em qualquer componente importado por um layout). Traduza cada correspondência usando a receita de seu cartão de erroblocking-prerender-*. -
Configurações de segmento incompatíveis. Pesquise por
^export const (revalidate|dynamic|fetchCache)emapp/e traduza de acordo com a nota derequisitosacima. O codemod não as toca; deixá-las no lugar falha a compilação após o codemod.
O codemod se recusa a executar em uma árvore de trabalho suja. Faça commit ou stash do trabalho não relacionado primeiro, ou passe --force para permitir que suas edições cheguem junto com seu WIP. Falso positivo comum: se você atualizou o Next.js recentemente, package.json e o arquivo de bloqueio já estarão sujos — faça commit deles primeiro.
Use o canal @canary