Communitygithub.com

next-cache-components-adoption

Ative os Cache Components em um aplicativo Next.js e resolva as rotas bloqueantes que surgem.

O que é next-cache-components-adoption?

Esta skill orienta a migração de um aplicativo Next.js App Router para usar Cache Components, garantindo que a compilação (build) passe com sucesso. Ela executa um loop estruturado: primeiro, você escolhe entre uma abordagem Incremental (silenciar erros de validação com um codemod e, em seguida, adotar rotas uma a uma em PRs separadas) ou uma Direta (habilitar a flag e corrigir as rotas bloqueantes sequencialmente). A skill lida com três classes principais de bloqueadores: leituras em tempo de requisição (como `cookies()`, `headers()`, `await params`), E/S síncrona em tempo de módulo/renderização (como `new Date()`, `Math.random()`) e arquivos `"use cache"` que leem dados de requisição. Para cada rota, o sucesso é definido por uma compilação limpa em `next dev` e uma compilação bem-sucedida em `next build`, com verificação por meio de navegador (de preferência usando a skill `next-dev-loop`). A skill é compatível com Next.js 16.3 ou superior e projetos App Router, exigindo que as chaves de configuração incompatíveis (`dynamic`, `revalidate`, `fetchCache`) sejam traduzidas para seus equivalentes de Cache Components.

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

Perguntar na sua IA favorita

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

Documentação

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: true não faz nada para rotas pages/. Se o projeto tiver uma árvore pages/ ou src/pages/ mas nenhuma árvore app/ ou src/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 (com pages/ e app/) é aceitável: a flag afeta as rotas app/; as rotas pages/ 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: cacheComponents de nível superior, export const instant, os avisos de validação de navegação instantânea no overlay de desenvolvimento e o codemod cache-components-instant-false. Se next --version mostrar uma versão inferior a 16.3, atualize primeiro:

  • Nenhuma chave de configuração incompatível. cacheComponents: true gera erro em qualquer arquivo que ainda exporte dynamic, revalidate ou fetchCache. 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 = 3600 para que o loop o pegue. O codemod cache-components-instant-false não toca nesses.

  • experimental.dynamicIO é fatal. Foi renomeado para cacheComponents de nível superior e a chave antiga agora aborta antes que qualquer compilação possa ser executada — remova-a (ou substitua por cacheComponents: true) primeiro. experimental.useCache ainda é aceito como um alias obsoleto; redundante uma vez que cacheComponents: true está 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 com please 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, execute npx @next/codemod@latest agents-md para escrever um índice correspondente à versão em AGENTS.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/fetchCache restantes), 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 cacheComponents e 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:

  1. Leituras em tempo de requisição (cookies(), headers(), await params, await searchParams). Todos os quatro bloqueiam quando usados com await no topo de uma página ou layout. params e searchParams muitas 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 para params/searchParams, encaminhe a promise para o filho e use await lá; não use await no topo da página.
  2. 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 com instant = 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 em await 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.
  3. Arquivos "use cache" que leem dados de requisição. Um arquivo com uma diretiva "use cache" de nível superior não pode exportar instant; combinar os dois gera erro com Only 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 do next 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-paths compila 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-prerender desabilita 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:

  1. next-dev-loop — fortemente preferido. Verifica cruzadamente /_next/mcp com o navegador ao vivo via agent-browser e 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 cutucar next dev manualmente.

    Instale-o antes de iniciar o loop. Não espere até encontrar algo que next dev sozinho não pode explicar. Execute:

    npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop
    

    A skill requer agent-browser >= 0.27.0 e o guiará através dela.

    Requer Turbopack. Se o script dev em package.json passar --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-loop em 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.

  2. Um navegador que você pode dirigir sozinho. Playwright, agent-browser diretamente, qualquer ferramenta de automação de navegador. Use apenas quando next-dev-loop estiver 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".

  3. 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.

  4. 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 cacheComponents e 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.

  1. E/S síncrona em tempo de módulo/renderização. Pesquise em todo o repositório por new Date(), Date.now(), Math.random() e crypto.randomUUID() (não apenas app/**/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 erro blocking-prerender-*.

  2. Configurações de segmento incompatíveis. Pesquise por ^export const (revalidate|dynamic|fetchCache) em app/ e traduza de acordo com a nota de requisitos acima. 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

Individual skills in this repo

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

Habilidades Relacionadas