Migración desde Next.js

Proceso de migración

Vinext ofrece herramientas automatizadas para migrar proyectos Next.js existentes.

Paso 1: Evaluar compatibilidad

npx vinext check

Este comando analiza tu proyecto en 4 etapas:

1. Imports — Escanea todos los imports next/* y evalúa soporte
2. Configuración — Revisa next.config.* por opciones reconocidas
3. Dependencias — Verifica librerías contra un mapa de compatibilidad
4. Estructura — Examina convenciones de archivos

El resultado es un score de compatibilidad en porcentaje. Un score alto (>80%) indica migración sencilla.

Paso 2: Ejecutar migración

npx vinext init

El comando vinext init realiza 7 pasos automáticamente:

1. Ejecuta vinext check
2. Instala dependencias (vinext, vite, @vitejs/plugin-rsc para App Router)
3. Actualiza React si es necesario (requiere >= 19.2.0)
4. Agrega "type": "module" al package.json
5. Renombra configs CJS a .cjs (ej: postcss.config.js → postcss.config.cjs)
6. Agrega scripts dev:vinext y build:vinext
7. Genera un vite.config.ts mínimo

La migración es no destructiva: tu setup de Next.js sigue funcionando. Puedes ejecutar ambos en paralelo.

Paso 3: Probar

npm run dev:vinext

Opciones de init

npx vinext init --port 3001       # Puerto del dev server (default: 3001)
npx vinext init --skip-check      # Saltar evaluación
npx vinext init --force           # Forzar sin confirmación

Lo que funciona directamente

Estructura de proyecto

• Directorios app/ y pages/ funcionan tal cual
• next.config.js es leído por Vinext (no necesitas otro archivo de config)
• rewrites, redirects, headers con interpolación de parámetros

Módulos reimplementados (33+)

Módulo	Soporte
next/link	Completo
next/image	Completo (via @unpic/react)
next/navigation	Completo
next/server	Completo
next/headers	Completo
next/cache	Completo
next/dynamic	Completo
next/script	Completo
next/font/google	CDN runtime (sin subsetting)
next/font/local	@font-face runtime
next/form	Completo
next/head	Completo (Pages Router)
next/router	Completo (Pages Router)
next/og	Parcial (sin módulos nativos en dev)

Variables de entorno

• NEXT_PUBLIC_* se inlinan en build time
• Variables privadas disponibles en servidor
• Funciones de config con argumento phase soportadas

Compatibilidad de librerías

Funcionan sin cambios

• next-themes — Funciona directamente
• nuqs — Maneja imports con extensión .js
• Librerías que usan solo APIs públicas next/*

Requieren trabajo adicional

Librería	Estado	Alternativa
next-intl	No soportado	Depende de build plugins internos de Next.js
next-auth	No soportado	Migrar a better-auth
@vercel/og	Solo producción	Módulos nativos no disponibles en dev

Limitaciones conocidas

Imágenes

• Sin optimización ni resize en build time
• Imágenes remotas procesadas vía CDN o endpoint /_vinext/image
• En Workers: usar binding de Cloudflare Images para transformaciones

Fonts

• Google Fonts cargadas desde CDN en runtime
• Sin font subsetting ni generación de fallback metrics
• Fonts locales inyectadas como @font-face en runtime

Módulos nativos

Módulos como sharp, satori, resvg y @napi-rs/canvas:

• No funcionan en desarrollo — causan crash
• Auto-stubbed en producción — Vinext los reemplaza automáticamente durante deploy
• Esto afecta rutas de generación de imágenes OG en dev

Otras limitaciones

Feature	Limitación
useSelectedLayoutSegment	Deriva segmentos del pathname (puede diferir en parallel routes)
runtime config	Ignorado (siempre ejecuta en edge)
preferredRegion	Ignorado
Turbopack/webpack config	No aplica (usar plugins de Vite)
next/jest	No soportado (usar Vitest)

Exclusiones intencionales

Vinext no implementa ni planea implementar:

• Features de Vercel: Analytics, KV, Blob, Postgres, @vercel/og edge runtime
• AMP: Deprecado desde Next.js 13
• next export: Comando legacy
• create-next-app: Usar vinext init en proyecto existente
• Paridad bug-por-bug: Enfoque pragmático al 95% de casos reales

Troubleshooting

”Module not found: next/…”

Verifica que vinext está instalado. El módulo next/* es resuelto internamente por Vinext a sus shims.

Error con módulos nativos en dev

Si ves errores con sharp, satori o similares en desarrollo:

• Es esperado — estos módulos no funcionan en el runtime de Vite
• Las rutas que los usan funcionarán en producción (auto-stub)
• Para dev, considera mockear o condicionar esas rutas

React version mismatch

Vinext requiere React >= 19.2.0 para Server Components:

npm install react@latest react-dom@latest

“type”: “module” conflicts

Si vinext init agrega "type": "module" y rompe scripts existentes:

• Renombra archivos CJS a .cjs (ej: jest.config.js → jest.config.cjs)
• O agrega extensión .mjs a archivos ESM

Build lento o falla

• Verifica que no hay configuración de webpack/turbopack conflictiva
• Elimina node_modules/.cache y .next si existen
• Ejecuta vinext check para identificar incompatibilidades

Rendimiento comparativo

Métrica	Next.js 16	Vinext (Vite 7)	Vinext (Vite 8)
Build (33 rutas)	7.38s	4.64s	1.67s
Bundle cliente (gzip)	168.9 KB	74.0 KB	72.9 KB
Speedup build	1x	1.6x	4.4x
Reducción bundle	—	-56%	-57%

Resumen del tutorial

A lo largo de estos 10 capítulos cubrimos:

1. Qué es Vinext y por qué existe
2. Instalación y estructura de proyecto
3. Pages Router con data fetching
4. App Router con layouts y streaming
5. SSR y React Server Components
6. Server Actions y formularios
7. Navegación, imágenes y SEO
8. Middleware y API routes
9. Despliegue en Cloudflare Workers
10. Migración desde Next.js

Vinext ofrece una alternativa viable para ejecutar aplicaciones Next.js fuera de Vercel, con mejor rendimiento de build y bundles más pequeños. Aunque es experimental, cubre el 94% de la API de Next.js 16 y está respaldado por Cloudflare.

Para más información, consulta el repositorio oficial de Vinext.