Actualizar Next.js de forma segura en proyectos heredados: un orden práctico

Por qué las actualizaciones de Next.js en proyectos heredados se sienten riesgosas

Un proyecto heredado suele significar que recibiste una base de código sin la historia detrás. El desarrollador original se fue, la documentación es escasa (o inexistente) y la app funciona porque un montón de suposiciones pequeñas coinciden por suerte. No sabes qué partes son sólidas y cuáles se mantienen por casualidad.

Las actualizaciones fallan con más frecuencia en esa situación. Las dependencias pueden estar fijadas por una razón que nadie anotó. Los scripts de build pueden depender de una versión específica de Node. Una librería puede estar deprecada pero aún "funcionando" solo porque nada más se ha movido. Cuando actualizas Next.js, esas suposiciones ocultas salen a la luz todas a la vez.

Los peores fallos son los que solo aparecen en tiempo de ejecución: todo parece bien localmente, pero producción se cae. Ejemplos comunes:

• La autenticación funciona en localhost pero falla detrás de un dominio real por cookies, CORS o cabeceras de proxy.
• Los builds tienen éxito, pero el servidor se cae al arrancar porque falta una variable de entorno.
• Las páginas renderizan localmente, pero la obtención de datos falla en producción por reglas de red más estrictas o timeouts.
• Los errores aparecen solo en cold starts, runtimes serverless o edge.
• Secretos se exponen o se bloquean porque la configuración de producción es diferente.

El objetivo no es la perfección. Es reducir el riesgo en pequeños pasos para que siempre sepas qué cambió y por qué. Diffs más pequeños, radio de impacto menor y una vía rápida de regreso si algo sale mal.

El éxito debe ser fácil de verificar: la app arranca, los flujos clave funcionan y los despliegues se mantienen estables. Para la mayoría de productos eso significa que la página principal carga, el login funciona, una acción central de negocio se completa (checkout, reserva, crear publicación) y los errores no suben tras el lanzamiento.

Antes de tocar código: acotación rápida en 20 minutos

La forma más rápida de hacer una actualización más segura es dedicar 20 minutos a averiguar qué estás cambiando realmente y dónde puede romper. La mayor parte del dolor de las actualizaciones viene de sorpresas, no del cambio de versión.

Empieza confirmando qué incluye la actualización. ¿Cambias Node, Next.js o ambos? También comprueba qué están usando realmente tu hosting y CI. Es común ver "una versión en los archivos de paquete" y otra diferente en producción.

Anota dónde corre la app hoy: tu portátil, CI, staging y producción. Una versión de Node que funciona localmente puede fallar en CI, y un build que pasa en CI aún puede estrellarse en tiempo de ejecución en el servidor.

Una lista rápida de acotación (sin leer todo el código):

• Versiones actuales y objetivo (Node y Next.js), además del gestor de paquetes (npm, pnpm, yarn).
• Dónde corre (local, CI, staging, producción) y quién posee cada uno.
• Los 5 flujos de usuario principales que no pueden romperse.
• Restricciones que no puedes cambiar rápido (versión de Node del hosting, base de datos, proveedor de auth, settings de edge/runtime).
• Alcance de la actualización (patch, minor, major) — elige el paso más pequeño que cubra tu necesidad.

Elige cinco flujos que puedas probar rápido. Si no puedes describir cada uno en una frase, no estás listo para cambiar versiones.

Un escenario común real: planeas un simple bump de Next.js y luego descubres que producción está fijada a una versión antigua de Node por el host. Eso convierte un cambio en un plan de dos pasos: alinear Node en todas partes y luego actualizar Next.js.

Congela una línea base para poder comparar cambios

Las actualizaciones asustan cuando no puedes saber si rompiste algo o si ya estaba roto. Antes de tocar versiones, fija una línea base a la que puedas volver.

Anota lo que tienes hoy: versión de Node, versión de Next.js, gestor de paquetes y lockfile. Si el repo tiene un archivo .nvmrc o un campo packageManager, pésalo. Si no lo tiene, eso es un riesgo temprano a corregir.

Después ejecuta lo que existe y registra lo que ya falla. Si hay tests, ejecútalos una vez y guarda la salida. Si no hay tests, crea una pequeña demo repetible que pruebe que la app arranca y que los flujos principales funcionan.

Asegúrate de que la línea base sea reproducible. Haz una instalación limpia desde cero (borra node_modules, reinstala, luego build y arranque). Si una instalación limpia falla, acabas de aprender algo importante antes de cualquier actualización.

Un script simple de "conocido bueno" para guardar en una nota:

• Instalación limpia de dependencias.
• Compilar la app.
• Arrancar el servidor.
• Recorrer 2–3 rutas clave (iniciar sesión, crear un elemento, cerrar sesión).
• Confirmar una o dos páginas que usan datos reales.

Guarda también logs de la línea base: uno de build y otro de start. Después de la actualización, esos logs son la forma más rápida de detectar nuevas advertencias, variables de entorno faltantes o caídas en tiempo de ejecución.

Un orden de actualización pequeño y seguro (Node, luego Next.js)

Mantén la secuencia aburrida y predecible: actualiza Node primero (a una versión que Next.js soporte), luego actualiza Next.js y después toca el resto del árbol de dependencias.

Elige tu versión objetivo de Next.js, comprueba qué versiones de Node soporta y elige una versión de Node que puedas ejecutar en todas partes (máquinas locales, CI y hosting). Para la mayoría de equipos eso significa una LTS actual, no la versión más nueva posible.

Saltar múltiples majors a la vez es donde las bases de código heredadas suelen romperse. Una división más segura se ve así:

• Mueve Node a la versión mínima soportada por tu Next.js objetivo.
• Ejecuta la app y los tests, y arregla solo lo que rompió el cambio de Node.
• Luego mueve Node a tu LTS preferida dentro del mismo rango de soporte.

Next.js va después de Node porque los cambios del framework (routing, output de build, comportamiento del servidor) son más difíciles de depurar cuando el runtime también cambia. Mantener esos diffs por separado aclara mucho qué causó un fallo nuevo.

Hay excepciones. Podrías actualizar Next.js primero si tu versión actual de Next.js no soporta ninguna versión de Node que puedas ejecutar en producción (por ejemplo, el hosting obliga a un Node más nuevo), o si un parche pequeño de Next.js es necesario para arrancar en tu Node actual. Si lo haces, mantenlo al mínimo y vuelve al orden normal.

Paso a paso: haz la actualización en movimientos controlados

Cambia una variable a la vez, mantén la app compilable y commitea con frecuencia. Así evitas convertir una pequeña actualización en una semana de conjeturas.

Primero, fija expectativas de runtime. Define la versión de Node que vas a usar (y hazla visible en engines). Asegúrate de que todos usen el mismo gestor de paquetes y las mismas reglas de lockfile. Muchos "bugs de actualización" son solo diferencias de versión de Node o un lockfile regenerado.

Un orden de movimientos controlados que funciona bien en repos desordenados:

• Actualiza Node (y settings del gestor), luego commitea.
• Borra node_modules, reinstala limpio, arregla errores de instalación, luego commitea.
• Ejecuta un build de producción, arregla bloqueadores de build (types, lint, variables de entorno faltantes), luego commitea.
• Actualiza Next.js (y React si es necesario), reinstala, compila de nuevo, luego commitea.
• Ejecuta localmente y reproduce tus flujos de línea base, luego commitea.

Durante las reinstalaciones, trata los errores de peer dependency y postinstall como señales. Si un paquete rompe la instalación, arréglalo primero en lugar de apilar problemas.

Después de cada build exitoso, ejecuta los mismos flujos clave que anotaste antes. Si tu script de línea base dice "iniciar sesión, crear un registro, actualizar, confirmar que persiste", haz eso después de cada commit. Aquí es donde atrapas rupturas que solo aparecen en tiempo de ejecución.

Nombra los commits por el cambio, no por el resultado (por ejemplo, "Bump Node a 20 y actualizar engines"). Si algo sale mal, puedes revertir un paso en lugar de deshacer todo un día de trabajo.

Cómo detectar fallos que solo aparecen en tiempo de ejecución temprano

Los errores de compilación son ruidosos. Los de tiempo de ejecución son más silenciosos y a menudo peores porque aparecen solo después del deploy, solo para ciertos usuarios o solo tras una redirección.

No confíes en un build exitoso como prueba de que tu app funciona. Después de una actualización, ejecuta la app como corre en producción: build de producción, valores de entorno realistas y cookies reales.

Formas rápidas de sacar a la luz problemas en tiempo de ejecución

Empieza ejecutando un build de producción localmente y luego arrancando el servidor. Esto detecta problemas que el modo dev oculta, como código que solo corre en el servidor en producción o módulos que se comportan diferente una vez empaquetados.

Luego presiona los puntos comunes de fallo en tiempo de ejecución:

• Variables de entorno: valores faltantes, claves renombradas o valores definidos solo en el proveedor de hosting.
• Imports dinámicos y código solo de servidor: APIs de Node que se filtran al bundle cliente.
• Problemas de hidratación: HTML que no coincide con lo que React espera, a menudo por usar window/localStorage demasiado temprano.
• Flujos de auth/sesión: cookies, flags secure, callback URLs, reglas de redirección.
• Diferencias de runtime: edge vs node, parsing de body, manejo de cabeceras, confiar en campos de la request que pueden no existir.

Un escenario común: el build funciona y la homepage carga, pero el login entra en bucle. La causa suele ser el comportamiento de cookies bajo HTTPS o una variable de callback URL desalineada entre entornos. Solo lo detectas probando el flujo completo de redirección de extremo a extremo.

Comprobaciones rápidas de regresión que ahorran horas

Después de una actualización no necesitas probar todo. Necesitas un puñado de comprobaciones que detecten los fallos más comunes rápido, especialmente en una app heredada.

Trata tu máquina como producción: haz un build de producción completo y luego arranca el servidor de la misma forma que en prod. Aquí aparecen muchas sorpresas de "funciona en dev".

Haz un pase rápido de variables de entorno antes de culpar al código. Las actualizaciones tienden a sacar a la luz deriva de configuración porque validaciones más estrictas o cambios de defaults hacen ruidosos problemas silenciosos.

Cinco comprobaciones de humo que suelen dar resultado:

• Cargar una página SSR y una página estática, luego refrescar ambas.
• Recorrer una ruta que use redirecciones o rewrites.
• Llamar a una ruta API de extremo a extremo, incluida la auth.
• Activar comportamiento de middleware (rutas protegidas, routing por locale).
• Ejecutar un efecto secundario real si la app lo tiene (subida, correo, webhook).

Observa la terminal y la consola del navegador por advertencias accionables. Las deprecaciones y avisos en tiempo de ejecución a menudo señalan exactamente lo que va a romper.

Trampas comunes y cómo evitarlas

Las actualizaciones heredadas se vuelven peligrosas cuando muchas cosas cambian a la vez. Mantén los cambios pequeños y facilita apuntar al commit exacto que introdujo la rotura.

Trampa 1: actualizar todo a la vez

Cuando Node, Next.js, React, ESLint y una docena de plugins se mueven juntos, pierdes el “por qué”. Mantén un orden simple, detente después de cada paso y verifica que la app aún arranca.

Trampa 2: árboles de dependencias distintos en máquinas distintas

Los lockfiles existen por una razón. Si el lockfile falta, se ignora o cambia constantemente, los desarrolladores instalarán conjuntos de dependencias distintos y obtendrán fallos distintos.

Elige un gestor de paquetes, comitea el lockfile, haz instalaciones limpias y usa la misma versión de Node en local, CI y producción.

Trampa 3: "arreglar" errores pinchando versiones al azar

Fijar un paquete hasta que el error desaparezca puede ocultar el problema real y hacer el proyecto más frágil. Antes de fijar, averigua si el error viene de un cambio breaking, un mismatch de peer dependency o una diferencia en la herramienta de build. Si debes fijar, anota por qué y planea eliminar la fijación.

Trampa 4: solo probar en modo dev

El modo dev de Next.js puede enmascarar problemas que aparecen en producción. Siempre ejecuta un build de producción y arráncalo localmente.

Trampa 5: secretos y deriva de configuración

Los proyectos heredados suelen tener archivos de env desordenados y claves hardcodeadas. Las actualizaciones de framework pueden cambiar el manejo de env y romper auth, storage o APIs de terceros.

Haz una comprobación rápida: lista las variables de entorno requeridas, confirma scopes y permisos, y asegúrate de que nada sensible esté comiteado.

Una lista de verificación simple para la actualización (imprimible)

Pega esto al lado del monitor. El objetivo es atrapar los fallos que convierten un pequeño bump en un fin de semana de conjeturas.

Ejecuta estas comprobaciones después de cada cambio controlado (después del bump de Node, luego del bump de Next.js). Si esperas hasta el final, pierdes la pista de qué paso causó la rotura.

• Instalación limpia y arranque: borra dependencias, instala desde cero y arranca la app con un comando.
• El build de producción es explicable: el build termina y las nuevas advertencias son entendibles.
• Los 5 flujos principales funcionan con datos realistas: usa datos reales o un dataset demo que se comporte como producción.
• Auth sobrevive uso real: iniciar/cerrar sesión funciona tras refrescar, en una nueva pestaña y después de cerrar y volver a abrir el navegador.
• Chequeo básico de seguridad: no hay secretos comiteados y no hay agujeros obvios de inyección en los caminos de código cambiados.

Si falla algún ítem, no sigas actualizando. Arregla hacia adelante en el paso más pequeño posible.

Si necesitas revertir, vuelve al último commit que pasó y reaplica cambios uno a uno. Compara uso de config y env (versión de Node, runtime, flags de build). Reduce el alcance deshabilitando features opcionales hasta que los flujos centrales pasen. Escribe una nota pequeña de regresión para que el retesting sea rápido.

Ejemplo: actualizar un prototipo frágil sin romper producción

Un fundador te entrega un prototipo Next.js generado por IA. Funcionó en demos, pero el primer deploy real falla: el servidor se cae al arrancar, la autenticación entra en bucle y algunas páginas quedan en blanco solo después de navegar.

El punto de partida suena familiar: versión antigua de Node, Next.js viejo, auth frágil copiado de snippets y una larga lista de dependencias nunca curada. El código corre en desarrollo, pero el build de producción es otra historia.

Mantienes el orden pequeño y predecible. Primero mueves Node a una LTS soportada y haces que el proyecto vuelva a compilar sin ningún otro cambio. Solo entonces actualizas Next.js. Después actualizas únicamente las dependencias que se rompieron por el cambio de framework.

Una secuencia práctica:

• Paso 1: Actualizar Node, reinstalar dependencias limpio, confirmar que la versión existente de Next.js aún compila.
• Paso 2: Actualizar Next.js (y React si hace falta), arreglar solo los errores que bloquean build o arranque.
• Paso 3: Aplicar actualizaciones de dependencia dirigidas (librería de auth, cliente fetch, ORM) según los fallos reales.

Antes de dar por terminado, ejecutas unas comprobaciones rápidas de regresión que detectan fallos que solo aparecen en tiempo de ejecución:

• Build y arranque de producción (no solo el servidor dev).
• Flujo completo de auth (iniciar sesión, refrescar, cerrar sesión).
• Una ruta API de extremo a extremo (request, validación, respuesta).
• Una página con muchos datos (carga, paginación, estado de error).

El resultado son menos incertidumbres: build estable, deploy funcionando y una lista corta y clara de problemas restantes para arreglar después.

Próximos pasos si la actualización sigue inestable

A veces la actualización no es el problema real. Es la base de código heredada. Si ves errores nuevos cada vez que arreglas uno, pausa. Forzar cambios puede convertir una actualización desordenada en un lanzamiento roto.

Detente y pide ayuda si esto sigue ocurriendo:

• La autenticación se rompe más de una vez (sesiones, cookies, redirects, middleware).
• Sospechas problemas de seguridad (secretos expuestos, inputs inseguros, consultas de base de datos extrañas).
• Los errores solo ocurren en producción y no los puedes reproducir localmente.
• Los stack traces apuntan a código generado que no entiendes o no confías.
• No puedes explicar qué cambió entre un build que funciona y otro que falla.

Si lo delegas, puedes ahorrar horas enviando un paquete limpio de contexto para que alguien empiece a probar rápido:

• Acceso al repo (o un zip) y el branch/commit exacto que quieres actualizar.
• Logs de error (salida de build, logs del servidor, salida de consola del navegador).
• El script de regresión que usaste para tu ejecución de línea base.
• Detalles de despliegue (hosting, manejo de env vars, versión de Node, comando de build).
• Versiones objetivo (Node y Next.js) y cualquier deadline.

Si el proyecto nació como un prototipo generado por IA y te topas con auth frágil, secretos expuestos o routing enmarañado, FixMyMess (fixmymess.ai) puede empezar con una auditoría de código gratuita para señalar qué bloquea una actualización segura y luego reparar y endurecer la base de código con correcciones verificadas por humanos.