Migrar un proyecto antiguo a Next.js 15 suena intimidante, pero el equipo de Vercel ha cuidado que el proceso sea casi indoloro. Si tienes una app en Next.js 11 y quieres llevarla a la versión 15, los codemods hacen el trabajo pesado por ti, paso a paso, versión por versión.

¿Qué son los codemods en Next.js y por qué importan?

Los codemods son scripts automatizados que aplican modificaciones de código preestablecidas para adaptar tu proyecto de una versión a otra. En lugar de revisar archivo por archivo, corres un comando y el script reescribe lo necesario.

¿Qué es un codemod? Es un script que transforma tu código fuente de forma automática siguiendo reglas predefinidas. Next.js los ofrece por cada versión mayor para acelerar migraciones.

Para seguir el ejercicio, parte del repositorio Platzi Next.js, un proyecto de hace más de tres años que corre originalmente con Next.js 11, React 17 y Semantic UI [01:05].

¿Cómo preparar el proyecto antes de migrar?

Antes de tocar nada, revisa tu package.json y confirma las versiones actuales de React, React DOM y TypeScript. Next.js exige mínimos en cada salto.

• React y React DOM deben subir a la versión 18 antes de pasar a Next.js 13.
• TypeScript necesita estar al menos en 4.5.
• Tu stage de Git debe estar limpio, porque los codemods lo exigen para correr.

Una vez actualizadas las dependencias con yarn install, haz un commit limpio. Sin commit, el codemod te lanzará un error y no avanzarás.

¿Cómo migrar de Next.js 11 a Next.js 13 paso a paso?

Este es el salto más grande y donde se concentran los cambios más visibles. Saltamos directo de la 11 a la 13 porque entre 11 y 12 los cambios son menores [02:30].

¿Qué codemods aplicar en la versión 13?

Son tres scripts que se ejecutan en orden, uno por uno, con su respectivo commit intermedio:

1. Next Image: actualiza la importación y sintaxis del componente Image.
2. Next Image Experimental: ajusta casos avanzados del nuevo Image.
3. New Link: elimina la etiqueta <a> interna del componente Link, un cambio muy controvertido en su momento pero esperado.

El codemod de New Link suele tocar la mayor cantidad de archivos. En el proyecto de ejemplo modificó 6 archivos automáticamente [04:40]. Cada codemod lanza workers en background, lo que hace el proceso rápido incluso en bases de código grandes.

¿Cómo continuar de Next.js 13 a 14 y luego a 15?

De la 13 a la 14 el procedimiento es idéntico: actualiza package.json, corre yarn install, commitea y aplica los codemods correspondientes.

¿Qué cambios trae Next.js 14?

Los codemods relevantes son Image Response y Viewport Export. En el proyecto de ejemplo ninguno tocó archivos, lo que confirma que la 13 a la 14 es una transición ligera para apps medianas.

¿Qué codemods corren en Next.js 15?

Aquí aparecen tres modificaciones clave:

• Geo and IP: solo aplica si despliegas en Vercel. Si usas Cloudflare u otro hosting, simplemente respondes que no y se omite.
• Async Request APIs: convierte llamadas que ahora requieren await, alineadas con el modelo asíncrono de la nueva versión.
• Runtime Config: transforma el directorio del runtime cuando tu proyecto lo usa.

¿Necesito async/await en Next.js 15? Sí, varias APIs de request ahora son asíncronas y deben llamarse con await. El codemod adapta tu código automáticamente.

¿Qué hacer después de migrar a Next.js 15?

Corre tu proyecto con yarn dev y verifica que cargue en localhost:3000. En el ejemplo, la app levantó en Next.js 15.0.4 sin tocar lógica de negocio [08:45]. Next.js además actualiza por debajo TypeScript y su archivo de configuración para dejarte el ambiente alineado.

¿Cómo activar Turbopack en Next.js 15?

Si instalaste desde cero con el instalador oficial, Turbopack ya viene habilitado. Para proyectos migrados, agrega la bandera --turbo a tu script de desarrollo en package.json, así tu yarn dev arranca con el nuevo bundler.

Ojo: en este ejemplo Turbopack lanzó un error de CSS porque Semantic UI está demasiado desactualizado. Next.js te da herramientas para migrar su propio código, pero el resto de tus dependencias también necesita actualizarse para que todo encaje.

¿Por qué confiar en este flujo de migración?

La estrategia funciona porque cada salto de versión queda aislado en su propio commit. Si algo se rompe, sabes exactamente en qué paso ocurrió y puedes revisar el diff sin ruido.

• Actualiza dependencias de Next, React, React DOM y TypeScript.
• Haz commit con mensaje claro tipo upgrade to Next.js 13.
• Corre los codemods de esa versión uno por uno.
• Commitea después de cada codemod aplicado.
• Repite para la siguiente versión.

Migrar tres años de evolución en menos de una hora demuestra que mantenerse al día con Next.js no tiene por qué ser un dolor de cabeza. ¿Has migrado alguna app legacy recientemente? Cuéntame en los comentarios qué versión te dio más batalla.