Heredar una base de código Next.js que nadie quiere tocar

Un equipo hereda una aplicación. Quienes la escribieron ya no están. Cada despliegue es un pequeño acontecimiento, nadie sabe con certeza qué partes sostienen el edificio, y en menos de un mes alguien dice la palabra "reescribir" en una reunión.

A veces reescribir es lo correcto. Lo es mucho menos a menudo de lo que se propone, y la decisión casi siempre se toma antes de que nadie tenga la información para tomarla.

Dos semanas leyendo antes de escribir una línea

La orientación que hacemos sobre una base de código heredada es fija: leer, mapear, documentar y no cambiar nada. Dos semanas, y el entregable es un documento, no un pull request.

Qué lleva dentro:

El mapa de rutas. Cada ruta, su modo de render, qué datos lee y cuáles escribe. En el App Router esto se recupera en buena parte de la salida del build y de los page.tsx; en una aplicación con Pages Router significa leer cuerpos de getServerSideProps. Es trabajo aburrido y es el artefacto más valioso de todos, porque "qué hace realmente esta aplicación" resulta ser una pregunta que nadie sabe responder.

La frontera de datos. Qué llamadas van a qué servicio, cuáles están autenticadas y cuáles cacheadas. Atención a la que nadie documentó: una API interna llamada desde un componente de cliente con una clave en NEXT_PUBLIC_.

El camino de despliegue. Qué lo construye, qué tests corren, cuáles son las variables de entorno y qué pasa cuando falla. Si la respuesta es "eso lo sabe Ali" y Ali se ha ido, ese es el punto más urgente de todo el documento.

El radio de impacto de cada área. Qué ficheros importa todo el mundo y cuáles importa una sola ruta. Un utils.ts compartido con cuarenta exports y cien importadores te dice dónde un cambio pequeño se vuelve grande.

Qué hace de verdad que una base de código sea difícil de cambiar

Después de auditar muchas, las propiedades que se correlacionan con el miedo son pocas y siempre las mismas.

• Sin tipos en las fronteras. No "sin TypeScript" - casi todos estos proyectos tienen TypeScript. Es any en cada fetch, de modo que el compilador valida el interior de la aplicación contra suposiciones que nadie comprobó en el borde.
• Estado en más de un sitio. Una caché de servidor, un store de cliente y parámetros de URL que dicen sostener el mismo valor, sin ninguna regla sobre cuál gana.
• Efectos secundarios en el render. Cadenas de useEffect que piden datos, luego fijan estado, luego disparan otro efecto. Son los cambios que rompen algo tres pantallas más allá.
• Sin costura entre el framework y el dominio. Reglas de negocio escritas dentro de route handlers no se pueden probar sin una petición, así que no se prueban.

Fíjate en lo que no está en la lista: dependencias viejas, una estructura de carpetas pasada de moda, componentes de clase, CSS que a alguien le disgusta. Eso es visible y barato de cambiar. No es lo que vuelve aterrador un despliegue, y una reescritura justificada así compra un año de riesgo a cambio de una mejora estética.

Primero segura, después buena

El orden importa, y no es el que resulta satisfactorio.

1. Hacer el despliegue reproducible. Mientras no puedas desplegar y revertir a voluntad, cada mejora es una apuesta.
2. Tipar las fronteras. Parsea los datos externos en el borde -con zod o equivalente- para que un dato mal formado falle en el fetch con un mensaje útil en vez de fallar tres componentes después como undefined is not a function.
3. Añadir tests donde está el dinero. No cobertura. El checkout, el flujo de autenticación, el cálculo del que depende el negocio.
4. Y entonces reestructurar, un área cada vez, detrás de esos tests.

Casi todo el miedo desaparece en el paso dos, y el paso dos suele ser una semana de trabajo sobre una base de código que se describía como insalvable.

Cuándo reescribir es de verdad la respuesta

Hay casos. En nuestra experiencia, merece la pena cuando el problema es el framework mismo: una aplicación construida sobre un meta-framework abandonado, o una cuyo modelo de render no puede producir las páginas que necesitas. También cuando la aplicación es lo bastante pequeña como para medir la reescritura en semanas, y entonces el debate casi da igual.

No merece la pena porque el código sea feo, porque esté en una versión mayor antigua, o porque no lo escribió el equipo actual. Esas son las tres razones por las que suele proponerse.

Y si el problema real es que la aplicación está en el Pages Router y el camino no está claro, tampoco eso es una reescritura: es migrar de Pages Router a App Router sin congelar el desarrollo, un trabajo distinto y mucho más barato.

Lo que le debes a quien venga después

Decidas lo que decidas, deja el documento. La base de código daba miedo porque el entendimiento del equipo anterior se fue con ellos, y el único arreglo duradero para eso es escribirlo donde el código pueda leerse al lado.

Ese mapa lo entregamos continúe o no el cliente con nosotros. Es la parte del encargo con la vida más larga.