---
title: "Vinext 1.0: como migrar seu app Next.js"
description: "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."
url: "https://www.escoladeaplicativos.com.br/arsenal/vinext-guia-migrar-nextjs"
author: "Mauro Mequelussi"
---

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

- **Organização:** Escola de Aplicativos (https://www.escoladeaplicativos.com.br)
- **Autores:** Mauro Mequelussi
- **Página canônica:** https://www.escoladeaplicativos.com.br/arsenal/vinext-guia-migrar-nextjs
- **Publicado em:** 2026-09-29T03:10:31.882638259Z
- **Atualizado em:** 2026-09-29T03:10:31.882693492Z
- **Tags:** open-source, nextjs, vite, cloudflare, workers, migracao

---

# Vinext 1.0: como migrar seu app Next.js

::callout{type="warning"}
**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

::code-demo{lang="bash" title="1. verificar o app"}
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

::code-demo{lang="bash" title="2. iniciar a migração"}
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:

::code-demo{lang="bash" title="3. deploy nos Workers com cache warming"}
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.

- Blog do lançamento: https://blog.cloudflare.com/vinext-nextjs-on-vite/
- Documentação e matriz de compatibilidade: https://vinext.dev/
- Código: https://github.com/cloudflare/vinext