Cómo migrar tu proyecto de Next.js 15 a Next.js 16 sin dolores de cabeza

Next.js 16 trae varios cambios de los que rompen build si migras a ciegas. Ninguno es difícil de resolver, pero conviene conocerlos antes de lanzar next dev y encontrarte con una pantalla roja. Este es el checklist que sigo al migrar un proyecto.

1. Corre el codemod primero

Antes de tocar nada a mano:

npx @next/codemod@latest upgrade latest

Actualiza next, react y react-dom a las versiones compatibles, y aplica automáticamente varias de las transformaciones que necesitas (incluyendo el rename de middleware.ts a proxy.ts). No lo hace todo, pero elimina la mayoría del trabajo mecánico.

2. Versión mínima de Node y React

Next.js 16 requiere Node.js 20.9 o superior y React 19. Si tu proyecto sigue en React 18, el codemod lo actualiza, pero revisa después las librerías de tu package.json que dependan de una versión concreta de React (algunas UI libraries tardan en dar soporte).

3. params y searchParams ya son 100% async

Next.js 15 los volvió asíncronos pero mantuvo un modo de compatibilidad que permitía acceso síncrono con warning. Next.js 16 elimina ese modo: acceder a params.slug directamente sin await ahora es un error, no un warning.

// ❌ Ya no funciona
export default function Page({ params }: { params: { slug: string } }) {
  return <h1>{params.slug}</h1>;
}

// ✅ Next.js 16
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  return <h1>{slug}</h1>;
}

Lo mismo aplica a searchParams en páginas y a cookies() / headers() en Server Components y Route Handlers.

4. Turbopack es el bundler por defecto

next dev y next build usan Turbopack sin necesidad de flags. Si tu proyecto dependía de un loader de Webpack muy específico (algunos plugins de SVG, workers, o configuración custom en next.config.js bajo webpack: () => {}), revisa que tenga equivalente en Turbopack o vuelve a Webpack explícitamente con next dev --webpack mientras migras esa pieza.

5. middleware.ts → proxy.ts

Cubierto en detalle en otro post, pero el resumen: renombra el archivo y la función exportada de middleware a proxy. El codemod del paso 1 ya se encarga si tu middleware es estándar.

6. Revisa next.config.js

Varias opciones marcadas como experimentales en Next.js 15 (experimental.ppr, experimental.after, algunas relacionadas con imágenes) cambiaron de nombre o se estabilizaron fuera de experimental. next build avisa con un mensaje claro de qué clave está obsoleta y cuál es su reemplazo.

Checklist de migración

---

La mayoría de proyectos migran en menos de una hora si siguen este orden: codemod primero, luego build, y arreglar lo que el propio compilador señale. Los errores de Next.js 16 son bastante específicos sobre qué cambió y cómo arreglarlo, así que la migración es más un ejercicio de paciencia que de investigación.