Guía para actualizar a Next.js 15

Next.js 15 trae mejoras importantes: compatibilidad con React 19, mecanismos de caché mejorados y una versión estable de Turbopack para desarrollo. En este tutorial te explico paso a paso cómo actualizar tu aplicación de Next.js a la versión 15, para que la transición sea fluida y saques el máximo partido a las novedades.

Requisitos previos

Antes de actualizar, asegúrate de tener:

• Una aplicación en Next.js 14
• Node.js 18 o posterior
• Una versión reciente de npm o yarn
• Una copia de seguridad de tu proyecto actual (recomendado)

Paso 1: actualiza las dependencias

Antes de seguir con la actualización, es fundamental actualizar las dependencias del proyecto para evitar problemas de compatibilidad.

Comprueba la versión actual

Ejecuta el siguiente comando para ver qué versión de Next.js tienes:

npx next --version

Si tienes una versión anterior, actualiza las dependencias:

npm install next@latest react@latest react-dom@latest eslint-config-next@latest

Si usas Yarn:

yarn add next@latest react@latest react-dom@latest eslint-config-next@latest

Después de actualizar, confirma las versiones instaladas:

npx next --version

Paso 2: actualiza next.config.js

Revisa tu archivo next.config.js en busca de opciones obsoletas y actualízalas según la documentación más reciente de Next.js.

Ejemplo:

const nextConfig = {
  experimental: {
    appDir: true,
    optimizeCss: true,
    optimizeFonts: true,
  },
  images: {
    domains: ['yourdomain.com'],
  },
};

module.exports = nextConfig;

Asegúrate de eliminar cualquier ajuste obsoleto y sustituirlo por la configuración recomendada.

Paso 3: prueba tu aplicación

Después de actualizar, arranca el servidor de desarrollo para detectar posibles problemas:

npm run dev

o

yarn dev

Revisa la salida de la consola en busca de advertencias y errores. Presta atención a las rutas de API, a los cambios en el middleware y a las funciones obsoletas.

Paso 4: migra las rutas de API al App Router

Next.js 15 mejora el enrutamiento de las API. Si usas el Pages Router para tus endpoints de API, plantéate migrarlos al App Router.

Ejemplo de migración

Antes (Pages Router)

// pages/api/hello.js
export default function handler(req, res) {
  res.status(200).json({ message: "Hello from API!" });
}

Después (App Router)

// app/api/hello/route.js
export function GET() {
  return Response.json({ message: "Hello from API!" });
}

Este cambio mejora el rendimiento y permite mejores estrategias de obtención de datos.

Paso 5: activa y optimiza Turbopack

Turbopack ya es estable en Next.js 15 y acelera notablemente las compilaciones.

Actívalo en package.json:

{
  "scripts": {
    "dev": "next dev --turbo"
  }
}

Arranca el servidor de desarrollo para comprobar las mejoras:

npm run dev

Paso 6: despliega la aplicación actualizada

Cuando la hayas probado en local, despliega la aplicación en tu proveedor de hosting preferido, como Vercel o Netlify.

git add .
git commit -m "Upgrade to Next.js 15"
git push origin main

Despliega la versión actualizada con Vercel:

vercel --prod

Problemas comunes y cómo solucionarlos

Problema 1: los estilos no se cargan

• Asegúrate de que las importaciones de CSS estén bien colocadas en layout.js para el App Router.
• Comprueba si optimizeCss está activado en next.config.js.

Problema 2: las rutas de API devuelven 404

• Asegúrate de que todos los endpoints de API sigan el nuevo formato del App Router.
• Reinicia el servidor de desarrollo después de hacer cambios.

Problema 3: caídas de rendimiento

• Revisa las peticiones de red en Chrome DevTools.
• Activa las optimizaciones de caché en next.config.js.

Conclusión

Actualizar a Next.js 15 te da acceso a nuevas funciones muy potentes, mejor rendimiento y una mejor experiencia de desarrollo. Con esta guía, la transición será fluida y podrás aprovechar sus últimas capacidades.

Para más detalles, consulta las notas oficiales de la versión Next.js 15: Documentación de Next.js 15.

Si actualizas las dependencias con cuidado, haces pruebas a fondo y aprovechas novedades como Turbopack y el App Router, sacarás el máximo partido a esta gran actualización.