Migración de React a Next.js

Una aplicación de página única y una aplicación Next.js no tienen la misma forma. La SPA pinta un div vacío y lo rellena desde el navegador; Next.js renderiza en el servidor y envía HTML. Todo lo que hace interesante esta migración sale de esa única diferencia, y nada de ello es mover ficheros.

Esta es la migración para equipos en Create React App, Vite o un montaje de React hecho a mano; no para quienes ya están en el Pages Router, que es otro problema con otro camino.

Qué cambia de verdad

Enrutado. Las rutas basadas en componentes de React Router pasan a ser un árbol de ficheros. Un <Route path="/products/:id"> se convierte en app/products/[id]/page.tsx. Las rutas anidadas con estructura compartida pasan a ser layouts anidados, que suele ser más simple que lo que había.

Obtención de datos. Aquí está el grueso del trabajo. Una SPA pide datos en useEffect tras montar, lo que significa un spinner, una cascada y nada que un rastreador pueda leer. En Next.js esa misma petición corre en el servidor antes de enviar la respuesta. El componente deja de gestionar estados de carga y pasa a ser una función async.

El bundle. En una SPA todo es código de cliente por definición. Tras la migración, la mayor parte no tiene por qué serlo: las rutas que movemos suelen perder entre un 40 % y un 60 % de su JavaScript, porque el árbol solo tiene que enviar lo que de verdad es interactivo.

Suposiciones de navegador. window, localStorage y document a nivel de módulo revientan en el servidor. Encontrarlos es mecánico; decidir cuáles van a un componente de cliente y cuáles nunca hicieron falta es el juicio.

El orden en que trabajamos

Next.js y tu SPA pueden servirse desde el mismo dominio durante la migración, así que nada tiene que pasar de golpe.

1. El armazón y una ruta hoja. Establece el layout, el helper de metadatos y las convenciones de datos sobre algo de bajo riesgo.
2. Las rutas que importan a los buscadores. Páginas de marketing, fichas de producto, todo lo público. Aquí está el retorno, porque son justo las páginas que no tenían HTML renderizado en servidor.
3. Rutas autenticadas. Paneles y ajustes. A menudo se quedan renderizadas en cliente y eso es correcto: detrás de un login no hay valor SEO, y al App Router no le molesta dejarlas interactivas.
4. El build viejo, borrado. No antes.

Qué puedes esperar ganar

La versión honesta: la mejora de rendimiento es real pero desigual, y la ganancia de SEO suele ser la mayor.

El primer pintado de una SPA espera a que el bundle se descargue, se parsee y se ejecute antes de que aparezca nada. El renderizado en servidor quita eso entero del camino crítico, y por eso el LCP mejora más en primeras visitas y cachés frías, y menos en un usuario que vuelve con la caché caliente.

El cambio de SEO es más categórico. Un rastreador que recibe un div vacío y una etiqueta de script no tiene nada que indexar. Tras la migración recibe el contenido. Para aplicaciones cuyas páginas públicas eran invisibles, eso no es una optimización: es la diferencia entre existir en los resultados de búsqueda y no existir.

Qué necesitamos ver primero

El repositorio, o una lista de rutas y qué pide cada una. La mayor parte de la estimación está en la capa de datos, no en el número de componentes: cien componentes de presentación se convierten en una semana, y un store global enredado puede llevar más que todos ellos juntos.

Qué recibes

La aplicación en Next.js, movida ruta a ruta, con las fases y un número de rutas por fase acordados antes de empezar. Cada fase es revisable por separado y deja detrás una aplicación que funciona.

Lo que más cambia es la capa de datos, así que la recibe documentada: qué pasó al servidor, qué se quedó en el cliente y por qué, y las llamadas a useEffect que resultaron estar haciendo algo que nadie recordaba.