PRNext e Next.js: guia de compatibilidade e migração

#Alinhe a versão e os pré-requisitos

Esta versão declara o Node ^22.23.4 || ^24.22.1 || >=26.12.1. Seus pares React, React DOM e react-server-dom-webpack são 19.3.1. Mantenha as dependências nativas opcionais habilitadas: o componente nativo deve corresponder à versão da estrutura.

Os comandos abaixo usam npm. Mantenha pnpm ou Yarn caso o projeto já os utilize e leia a documentação enviada no pacote. Trabalhe em uma ramificação ou cópia isolada, preservando o lockfile original. Os pacotes nativos publicados não exigem que os consumidores instalem Rust.

node --version
npm install --save-exact @thomas.f/prnext@0.1.18-alpha react@19.3.1 react-dom@19.3.1 react-server-dom-webpack@19.3.1
npx --no-install prnext migrate --dry-run
npx --no-install prnext migrate --check --json

#Identifique recursos que precisam de verificações focadas

Convenções de roteamento, componentes de servidor, ações, navegação e estilos estão entre as áreas adaptadas pelo PRNext. O escopo depende da configuração e do caminho executado. Esta matriz identifica verificações de aplicativos em vez de atribuir compatibilidade universal a cada família de recursos.

#Leia o plano antes de aplicar a migração

A simulação permite revisar o script proposto e as alterações de dependência. A auditoria também deve identificar conflitos de configuração e origem. Mantenha um arquivo next.config.* ou prnext.config.*; renomeá-lo não torna uma opção Next.js desconhecida suportada.

Quando o plano for apropriado, aplique a migração, verifique a configuração e o build. typecheck requer TypeScript e um tsconfig no aplicativo. A migração retém fontes e Next.js; as importações públicas next/* podem permanecer. Evite substituições gerais de importação ou ocultação de conflitos entre pares com --force.

npx --no-install prnext migrate
npx --no-install prnext check --json
npx --no-install prnext typecheck
npx --no-install prnext build

#Compare respostas de servidores separados

Inicie a referência Next.js em uma porta disponível e a candidata em outra. paths.json contém uma matriz JSON de rotas concretas, como ["/", "/products/demo", "/api/health"], substituída pelos caminhos do seu aplicativo. Mantenha cookies e segredos fora disso.

O comparador verifica amostras de respostas GET públicas. Ele não autentica solicitações nem segue redirecionamentos. Seus tempos não são uma referência controlada. Um resultado favorável ainda requer verificações do navegador quanto a estilo, hidratação, mutações e estados autenticados.

npx --no-install prnext migrate --check --against http://127.0.0.1:3000 --candidate http://127.0.0.1:3001 --routes paths.json

#Verifique as jornadas que fazem o produto funcionar

Exercite login, logout e uma ação comercial. Verifique a navegação, erros, estados de carregamento e cookies. Para um formulário, verifique o resultado armazenado e o estado exibido após a resposta. O status HTTP não descreve toda a interação.

Adicione verificações de isolamento com duas sessões: respostas privadas e dados armazenados em cache não devem cruzar entre elas. Se você usar importações Next.js privadas, carregadores personalizados ou roteamento avançado, mantenha um exemplo mínimo do caminho testado. Essas dependências podem alterar a avaliação.

#Decidir após verificação funcional

Mantenha a versão exata, lockfile, casos testados e eventuais incompatibilidades. Se um recurso estiver faltando, identifique o API e o cenário envolvido. Uma limitação precisa é mais útil do que uma porcentagem geral de compatibilidade.

Em seguida, meça rotas caras sob restrições de recursos correspondentes. Guarde a referência até que o candidato atenda aos seus critérios. As migrações de banco de dados precisam de seu próprio plano de reversão; restaurar package.json não os desfaz.

Escolha PRNext para os requisitos da sua aplicação

Medir SSR após verificação funcional