¿Qué hace Protocolo de actualización de Next.js?
Pasos de migración automatizados y manuales para actualizaciones de versión de Next.js (p. ej., v14 → v15).
Prioridad: P1 (OPERATIVO)
Directrices de implementación
- Detección de actualización: Siempre verifica
package.jsonpara las versiones denext,reactyreact-dom. - Planificación: Para saltos de versión mayor (v13 a v15), realiza una actualización incremental (v13 -> v14, luego v14 -> v15). Sigue las Guías de migración oficiales de Next.js.
- Codemods automatizados: Usa
npx @next/codemod@latest <transform> <path>para automatizar la migración de sintaxis. - Cambios disruptivos (v15): Responde a la transformación
next-async-request-apiasegurando queparams,searchParams,cookies()yheaders()sean esperados. - Paridad de React: Actualiza
reactyreact-dompara que coincidan con las dependencias de pares de Next.js (p. ej., React 19 para Next.js 15). - Validación: Ejecuta
next devynext builddespués de cada paso incremental. Verifica los errores de consola en busca de advertencias de hidratación. - Reporte: Reporta todas las fallas de codemod o correcciones manuales necesarias al equipo.
3. Actualización de dependencias
Actualiza Next.js y las dependencias de pares en sincronía:
# Usando npm
npm install next@latest react@latest react-dom@latest
# Actualizar tipos
npm install --save-dev @types/react@latest @types/react-dom@latest
4. Reglas de verificación manual
- Contexto asíncrono: Verifica que todos los usos de
cookies(),headers()yparamsde rutas ahora sean esperados. - Metadatos: Asegúrate de que los tipos de
generateMetadatacoincidan con la nueva firma asíncrona deparams. - Almacenamiento en caché: En v15+,
fetchpor defecto usa{ cache: 'no-store' }. Si necesitas el comportamiento anterior, establece explícitamente{ cache: 'force-cache' }.
5. Prueba de compilación
- Ejecuta
npm run buildinmediatamente después de los codemods y actualizaciones de paquetes. - Verifica si hay errores de "Falló la hidratación" o de compatibilidad con "Turbopack" si se usa
--turbo.
Anti-patrones
- Sin salto de versión mayor: Actualiza una versión mayor a la vez (13→14, luego 14→15).
- Sin correcciones manuales de cambios disruptivos: Siempre ejecuta primero las transformaciones de
npx @next/codemod@latest. - No asumir comportamiento de caché post-actualización: v15 por defecto usa
no-store; audita todas las llamadasfetch. - Sin funciones de página asíncronas en Pages Router:
export default async function Page()es fatal.