VOLTAR_AO_ARSENAL
ARSENAL OPEN-SOURCENEXTJSVITE

Vinext 1.0: como migrar seu app Next.js

Passo a passo para migrar um app Next.js para o Vinext 1.0: o check, o init, o deploy com aquecimento de cache e o que o 1.0 ainda não cobre.

29_DE_SET_DE_2026 4_MIN
Mauro Mequelussi

Mauro Mequelussi

Vinext 1.0: como migrar seu app Next.js

Ressalva de método. Guia feito a partir do anúncio oficial da Cloudflare, do site do projeto e do repositório — não é um teste de migração real executado aqui. Conferido: os comandos publicados, o que o 1.0 trouxe, o que ficou de fora e os limites declarados. Não testado: migrar um app Next.js de produção, medir o ganho de build e validar o aquecimento de cache sob tráfego.

O problema que o Vinext resolve

Você construiu o produto em Next.js — o framework mais usado para apps em React — e na hora de mudar de hospedagem descobre que o app ficou amarrado ao jeito como foi publicado. Migrar parece reescrever tudo, e é aí que a decisão trava.

O Vinext ataca isso sendo um adaptador de tomada, não um framework novo: seu app continua igual, só muda o encaixe. Ele imita o comportamento do Next.js — não só os nomes das funções — e usa o Vite por baixo.

Passo a passo

1. Confira a compatibilidade antes de mexer em qualquer coisa

npx vinext check

Este comando é o passo que não se deve pular: ele confere se o seu app é compatível e aponta o que precisa de ajuste. Personalizações no projeto são justamente o que costuma exigir trabalho.

2. Migrar o projeto

npx vinext init

O init configura o Vite e a publicação sem mudar a estrutura do projeto. É o que mantém a migração barata: você não reescreve os caminhos nem a organização das páginas.

3. Publicar onde quiser

O mesmo app roda no plano gratuito do Cloudflare Workers, na Netlify ou na AWS Lambda. Para publicar nos Workers com o aquecimento de cache ligado:

npx @vinext/cloudflare deploy --warm-cache

4. Resolva o build que não termina

Site com dezenas de milhares de páginas passa horas gerando página a página na máquina de build — e boa parte delas quase não recebe tráfego. O Vinext move essa renderização para a rede da Cloudflare (é o cache warming): a nova versão sobe com 0% do tráfego, a rede gera as páginas, e só então a versão entra no ar. O build deixa de ser o gargalo.

5. Entenda o que sustenta a compatibilidade

O Vinext suporta as duas formas de montar rotas do Next.js — a antiga (Pages Router) e a nova (App Router) — inclusive as duas no mesmo app, com React Server Components, Server Actions, API routes, route handlers, middleware e navegação client-side. A compatibilidade passa de 99% nos recursos que os clientes mais pediram, medida toda noite rodando a bateria de testes do próprio Next.js contra o Vinext. Também há tracing compatível: OpenTelemetry e Sentry continuam funcionando.

Limites e cuidados

  • "use cache" (Cache Components, do Next.js 16) tem suporte limitado. A equipe priorizou o que os clientes de fato usam. Se a sua aplicação aposta nesse recurso, a migração não é agora.
  • Rode o check primeiro, sempre. Ele é o único jeito de saber se o seu caso está coberto antes de gastar tempo.
  • Compatibilidade alta não é 100%. Sobra uma cauda de comportamentos que não bate com o Next.js — e é aí que um app real encontra o problema.
  • Aquecimento de cache é da Cloudflare. Em Netlify ou AWS Lambda o app roda, mas esse ganho de deploy é do caminho Cloudflare.
  • Projeto novo, mas já em produção: clientes rodam Vinext em produção em apps de muito tráfego; a manutenção é feita por agentes que leem as mudanças do Next.js e propõem correções — o que reduz, mas não elimina, a defasagem em relação ao upstream.

Por onde começar

Se o seu app é um Next.js pequeno e você só quer sair da amarração de hospedagem: rode npx vinext check, veja o relatório e decida. Se o seu caso é o build lento com muitas páginas, o teste que importa é outro — migrar um ambiente de staging, publicar com --warm-cache e comparar o tempo até a página estar servida. Comece por um app interno, não pelo que fatura.