Protocolo de Upgrade do Next.js
Etapas de migração automatizadas e manuais para upgrades de versão do Next.js (ex.: v14 → v15).
Prioridade: P1 (OPERACIONAL)
Diretrizes de Implementação
- Detecção de Upgrade: Sempre verifique o
package.jsonpelas versões denext,reactereact-dom. - Planejamento: Para saltos de versão principal (v13 para v15), realize um upgrade incremental (v13 -> v14, depois v14 -> v15). Siga os Guias de Migração do Next.js oficiais.
- Codemods Automatizados: Use
npx @next/codemod@latest <transform> <path>para automatizar a migração de sintaxe. - Mudanças Críticas (v15): Responda à transformação
next-async-request-apigarantindo queparams,searchParams,cookies()eheaders()sejam usados comawait. - Paridade com React: Atualize
reactereact-dompara corresponder às dependências pares do Next.js (ex.: React 19 para Next.js 15). - Validação: Execute
next devenext buildapós cada etapa incremental. Verifique os erros no Console para avisos de hidratação. - Relatórios: Reporte todas as falhas de codemod ou correções manuais necessárias à equipe.
3. Atualização de Dependências
Atualize o Next.js e as dependências pares em conjunto:
# Usando npm
npm install next@latest react@latest react-dom@latest
# Atualizar Types
npm install --save-dev @types/react@latest @types/react-dom@latest
4. Regras de Verificação Manual
- Contexto Assíncrono: Verifique se todos os usos de
cookies(),headers()eparamsde rota agora usamawait. - Metadados: Garanta que os tipos de
generateMetadatacorrespondam à nova assinatura assíncrona deparams. - Cache: Na v15+,
fetchpadroniza para{ cache: 'no-store' }. Se precisar do comportamento antigo, defina explicitamente{ cache: 'force-cache' }.
5. Testando o Build
- Execute
npm run buildimediatamente após os codemods e atualizações de pacotes. - Verifique erros de "Hydration failed" ou de compatibilidade com "Turbopack" ao usar
--turbo.
Anti-Padrões
- Sem pular versão principal: Atualize uma versão principal por vez (13→14, depois 14→15).
- Sem correções manuais para mudanças críticas: Sempre execute primeiro as transformações
npx @next/codemod@latest. - Sem comportamento de cache presumido pós-upgrade: v15 padroniza para
no-store; audite todas as chamadasfetch. - Sem funções de página assíncronas no Pages Router:
export default async function Page()é fatal.