Convivir con lo heredado: reconocer, congelar y migrar sin sobresaltos

Hay una diferencia grande entre saber que algo es legado y saber trabajar con ello. Lo primero es una opinión y se adquiere leyendo una nota de producto; lo segundo es un oficio y se nota en cuánto tarda un equipo en tocar un proyecto que nadie ha abierto en dieciocho meses sin romperlo. Los proyectos de Pages son ahora mismo, y lo seguirán siendo durante años, una porción real del software que se mantiene en producción: sitios corporativos, documentaciones, paneles internos, campañas que sobrevivieron a sus campañas. Ese código no está mal escrito ni es despreciable; simplemente responde a un modelo que la plataforma ya superó. La tarea del ingeniero frente a él tiene tres tiempos muy distintos y conviene no mezclarlos: reconocerlo con rapidez, congelarlo para que deje de acumular deuda, y traducirlo cuando exista una razón de negocio que lo justifique, no antes ni bajo pánico.

Reconocerlo en treinta segundos

Un proyecto heredado se delata en el repositorio antes que en el panel. Estas cuatro señales bastan para clasificarlo sin preguntar a nadie, y conviene buscarlas en ese orden porque cada una implica un trabajo de migración distinto.

A esas señales se suman las de operación: un dominio terminado en pages.dev, un _routes.json en la carpeta pública, o un panel donde el proyecto aparece bajo la sección de Pages en lugar de la de Workers. Ninguna de ellas es un problema por sí misma; juntas te dicen exactamente cuánto trabajo hay por delante.

Congelar antes que migrar

El error más caro no es tardar en migrar: es seguir invirtiendo en el proyecto mientras decides. Cada capacidad nueva que se añade a un proyecto heredado es trabajo que habrá que traducir después, y se añade justo en el momento en que menos se piensa en la traducción. Por eso el primer movimiento no es técnico sino de política, y cuesta cero.

La traducción, pieza a pieza

Con el proyecto congelado e inventariado, la migración deja de ser una aventura y se vuelve una tabla de correspondencias. Requiere Wrangler en versión cuatro o superior; con eso, cada concepto de Pages tiene su equivalente exacto.

Si el proyecto tiene funciones, el paso ineludible es compilarlas: el comando de Wrangler las convierte en un único script de Worker que conserva el enrutado por archivos, y ese script pasa a ser el punto de entrada. El comando se mantiene disponible de forma indefinida como puente, aunque la recomendación oficial para proyectos que quieran seguir con rutas por convención es adoptar un framework que las ofrezca de forma nativa.

npm install --save-dev wrangler@^4.0.0
npx wrangler pages functions build --outdir=./dist/worker/
npx wrangler deploy --dry-run

{
  "name": "mi-app",
  "compatibility_date": "2026-07-30",
  "main": "./dist/worker/index.js",
  "assets": {
    "directory": "./dist/client/",
    "binding": "ASSETS",
    "run_worker_first": true
  }
}

El otro ajuste de traducción está en el cuerpo del código. Donde una función llamaba a context.next para delegar en el sitio estático, un Worker recupera el archivo a través del binding declarado, que es el mismo mecanismo con otro nombre.

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    if (url.pathname.startsWith("/privado/") && !(await autorizado(request, env))) {
      return new Response("No autorizado", { status: 401 });
    }
    return env.ASSETS.fetch(request);
  },
} satisfies ExportedHandler<Env>;

Migrar por fases, con retorno en cada paso

La migración no debería ser un evento sino una secuencia en la que cada paso es reversible y observable. El proyecto de Pages sigue en producción hasta el último momento, y el Worker nuevo se gana el dominio solo después de demostrar que sirve lo mismo.

flowchart TD
A[proyecto de pages en produccion] --> B[congelar y hacer inventario]
B --> C[worker espejo en dominio de prueba]
C --> D[comparar rutas cabeceras y redirecciones]
D -->|diferencias| C
D -->|paridad verificada| E[mover el dominio al worker]
E --> F[observar y mantener pages listo]
F -->|todo estable| G[retirar el proyecto de pages]
F -.incidencia.-> A
style C fill:#89b4fa,color:#11111b
style E fill:#f9e2af,color:#11111b
style G fill:#a6e3a1,color:#11111b

La fase que más se subestima es la tercera, la comparación. No basta con que la portada cargue: hay que verificar las redirecciones con comodín, las cabeceras de caché por patrón, el comportamiento ante rutas inexistentes y, sobre todo, las rutas que pasaban por middleware. Un guion que recorra el inventario pidiendo cada ruta a los dos orígenes y comparando código de estado y cabeceras convierte esa fase en un problema medible en lugar de una inspección a ojo.

while read ruta; do
  a=$(curl -s -o /dev/null -w "%{http_code} %{redirect_url}" "https://viejo.ejemplo.com$ruta")
  b=$(curl -s -o /dev/null -w "%{http_code} %{redirect_url}" "https://nuevo.ejemplo.com$ruta")
  [ "$a" = "$b" ] || echo "DIFIERE $ruta -> viejo=$a nuevo=$b"
done < inventario-rutas.txt

Ese guion de seis líneas hace algo que ninguna revisión manual consigue: convierte la paridad en un criterio binario y repetible. Puedes ejecutarlo tras cada ajuste, dejarlo en la tubería de integración mientras dure la convivencia y usar su salida vacía como la señal que autoriza mover el dominio. Amplíalo con las cabeceras que te importen —la de caché es la que más silenciosamente se pierde— y tendrás cubierto el noventa por ciento de lo que suele fallar.

La quinta fase, la retirada, tiene su propia disciplina. Mantén el proyecto de Pages desplegado y accesible por su dirección de origen durante un ciclo completo de facturación y observación, porque es tu vuelta atrás real: si aparece un problema grave, devolver el dominio es una operación de segundos frente a la alternativa de depurar bajo presión. Solo cuando hayan pasado semanas sin incidencias tiene sentido borrar el proyecto, y conviene hacerlo de forma explícita en vez de dejarlo ahí: un proyecto olvidado que sigue compilando en cada push es una fuente futura de confusión y, si tenía secretos, una superficie de riesgo que nadie está vigilando.