Migrar entre herramientas

Migrar entre orquestadores tiene fama de proyecto grande y arriesgado, y esa fama es casi siempre injusta. La razón está en la arquitectura de capas que estas lecciones insisten en separar: debajo vive pnpm con sus workspaces, y encima se sienta el orquestador —Turborepo, Nx o Moon— que se limita a leer ese sustrato para orquestar tareas. Migrar, entonces, no toca la capa que de verdad define tu monorepo; sustituye la capa superior, que es fina y reversible. El trabajo real de una migración no es mover código sino traducir una declaración: el mismo grafo de tareas que ya existe, expresado en otra sintaxis. Esta lección disecciona qué sobrevive intacto a ese cambio, qué hay que volver a escribir, cómo hacerlo sin detener el desarrollo ni un día, y —lo más importante— cómo distinguir las pocas señales que justifican migrar de las muchas que solo disfrazan una moda.

Qué se conserva y qué cambia

Para migrar sin miedo hay que saber con exactitud qué se mueve y qué no. La respuesta es nítida porque sigue la frontera entre capas: todo lo que vive en la capa de pnpm se conserva intacto, y solo lo que vive en la capa de orquestación se reescribe.

Del lado de lo que se conserva está el sustrato entero. El pnpm-workspace.yaml que enumera tus paquetes no cambia una coma. Los scripts de cada package.json siguen ahí, porque son la definición real de qué hace cada tarea —compilar, testear, lintar— y ningún orquestador los reemplaza, solo los invoca. Y, sobre todo, se conserva lo más valioso y lo que más costó construir: la topología del grafo, es decir, qué paquete depende de cuál y en qué orden deben ejecutarse las tareas. Esa estructura es una propiedad de tu código, no del orquestador, y por eso sobrevive a cualquier cambio de herramienta.

A ese sustrato pertenece también toda la capa de instalación, que la migración ni roza: el pnpm-lock.yaml que fija las versiones exactas, el node_modules que pnpm enlaza desde su store, y el .npmrc con su política de hoisting siguen siendo asunto de pnpm y de nadie más. El orquestador nunca instala nada; se limita a ejecutar tareas sobre un árbol de dependencias que ya existe. Por eso una migración de orquestador y una migración de gestor de paquetes son operaciones de naturaleza distinta y de coste incomparable: la primera reescribe un archivo de pipeline; la segunda tocaría la capa que de verdad sostiene todo.

Del lado de lo que cambia hay, en realidad, una sola cosa expresada de dos formas: la declaración del pipeline y la configuración de la caché. Cada orquestador tiene su propio archivo y su propia sintaxis para decir lo mismo —qué tarea depende de qué, qué archivos son entrada, qué archivos son salida—. Migrar es traducir esa declaración de un dialecto a otro. La tabla siguiente muestra que la traducción es casi un isomorfismo: los conceptos son idénticos, solo cambian los nombres y el archivo donde viven.

La misma tarea de build, en dos dialectos, deja ver el isomorfismo con toda claridad. Turborepo envuelve el script que ya vive en el package.json; Moon prefiere declarar el comando explícito. Cambia la piel, no el esqueleto:

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**"],
      "outputs": ["dist/**"]
    }
  }
}

tasks:
  build:
    command: tsc --build
    deps: ["^:build"]
    inputs: ["src/**"]
    outputs: ["dist"]

flowchart TD
sustrato[pnpm workspaces scripts y grafo] --> conserva[se conserva intacto]
orquestador[capa de orquestacion] --> cambia[se vuelve a declarar]
cambia --> pipe[pipeline de tareas]
cambia --> cache[claves e inputs de cache]
style conserva fill:#a6e3a1,color:#11111b
style cambia fill:#eba0ac,color:#11111b

Hay una excepción crucial a la simetría, y es la caché. Aunque los conceptos de inputs y outputs se traducen uno a uno, la caché acumulada no se traslada: cada herramienta calcula el hash de una tarea con su propio algoritmo, así que un acierto de Turborepo no significa nada para Nx. El primer día tras migrar, tu caché remota vale cero y todo se reconstruye una vez. No es un fallo, es la naturaleza de la caché por contenido: el hash es un contrato interno de cada herramienta, y cambiar de herramienta lo invalida por completo.

Una transición incremental sin parar el desarrollo

La forma ingenua de migrar es el big bang: arrancar el orquestador viejo, enchufar el nuevo y rezar, todo en un único PR gigante. Es tentador porque parece rápido, pero paraliza el desarrollo mientras se estabiliza y no deja vía de vuelta si algo falla en producción. La forma profesional es la contraria: operación en paralelo, donde ambos orquestadores conviven hasta que el nuevo se gana la confianza.

La estrategia se apoya en cuatro pasos, y su columna vertebral es que los scripts siguen siendo la fuente de verdad durante todo el proceso:

1. Instala el nuevo junto al viejo, sin borrar nada. Ambos leen el mismo pnpm-workspace.yaml y los mismos scripts, así que coexisten sin conflicto: son dos lectores del mismo sustrato, no dos dueños que se disputan el repo.
2. Traduce el pipeline tarea por tarea, de la más simple a la más compleja. Empieza por lint o typecheck, que no tienen dependencias, y sube hacia build y test. Cada tarea traducida se verifica antes de pasar a la siguiente.
3. Corre los dos en el CI en paralelo un tiempo. El viejo sigue siendo la fuente de verdad que bloquea el merge; el nuevo corre como sombra que reporta pero no bloquea. Cuando el nuevo lleve semanas coincidiendo, invierte los papeles.
4. Retira el viejo en un PR pequeño. Cuando el nuevo orquestador es la fuente de verdad y el equipo confía en él, un único commit que solo borra la configuración vieja cierra la migración.

Instalar los dos a la vez es literalmente un add en la raíz del workspace, y a partir de ahí cada uno se invoca con su propia sintaxis sobre el mismo grafo:

# ambos orquestadores instalados, leyendo el mismo workspace
pnpm add -Dw turbo nx
# el viejo manda en el merge; el nuevo corre en sombra
turbo run build
nx run-many -t build

flowchart LR
A[scripts como fuente de verdad] --> B[instala el nuevo en paralelo]
B --> C[traduce y compara una tarea]
C --> D[ci en sombra sin bloquear]
D --> E[invierte y retira el viejo]
style A fill:#89b4fa,color:#11111b
style E fill:#a6e3a1,color:#11111b

El punto de control de cada paso es la equivalencia de salidas. Antes de confiar en la traducción de una tarea, corre esa tarea con las dos herramientas sobre el mismo commit y compara sus artefactos: si el dist que produce Nx es byte a byte el que producía Turborepo, la traducción fue fiel. Esa comparación objetiva sustituye a la fe y convierte la migración en una serie de pequeñas verificaciones en vez de un salto ciego.

Hay un único trozo de fontanería que sí es nuevo y merece atención aparte: las credenciales de la caché remota. El pipeline se traduce, pero el token que autentica contra Vercel Remote Cache, Nx Cloud o el backend que uses es una pieza de infraestructura de CI que hay que aprovisionar de cero para el orquestador nuevo. Es poca cosa —una variable de entorno secreta y su conexión en el runner— pero es lo que separa un CI que reutiliza la caché de uno que reconstruye todo en cada corrida, así que conviene tenerlo listo antes de invertir los papeles.

Señales para migrar y señales para no hacerlo

La parte técnica de una migración es la fácil; la difícil es decidir si debe ocurrir. Como la capa de orquestación es reversible y barata de cambiar, la tentación de migrar por cualquier motivo es alta, y ahí está el error. La regla es simple de enunciar y difícil de obedecer: migra por un dolor concreto y presente que la herramienta actual no resuelve; no migres por nada más.

La señal para no migrar más importante y más ignorada es la más aburrida: que la herramienta actual todavía encaja. Un orquestador que resuelve tu dolor de hoy no necesita ser reemplazado porque exista uno más admirado; la ausencia de dolor es una respuesta completa, no un vacío que haya que llenar con novedad. Antes de traducir una sola línea de pipeline, exige que exista un dolor que puedas escribir en una frase; si esa frase no aparece, la migración correcta es la que no haces.

Y cuando la decisión sí es legítima, presupuesta el periodo de paralelo como lo que es: la fase donde de verdad se paga la migración. Correr dos orquestadores en el CI cuesta minutos de runner y atención del equipo, y ese doble gasto dura semanas, no horas. Es dinero bien invertido —compra la certeza de que el nuevo es equivalente antes de depender de él— pero hay que nombrarlo por adelantado, porque una migración que nadie presupuestó se abandona a medias en cuanto el primer sprint aprieta, y un repo con dos orquestadores instalados y ninguno retirado es peor que cualquiera de los dos por separado.