Migrar de v4 a v5: inventario de roturas y ruta segura

Migrar de la v4 a la v5 es incómodo por una razón que conviene nombrar sin rodeos: no es una limpieza de API, es un cambio de modelo mental que arrastra consigo un cambio de nombres. El actor pasa a ser la unidad central y por eso services se llama actors; la declaración precede a la construcción y por eso el segundo argumento de createMachine cede su sitio a setup; la inferencia ocurre en el compilador y por eso el generador de tipos desaparece entero, con su CLI y sus ficheros. Quien intente migrar con buscar y reemplazar acertará en la mitad de los casos y se estrellará en la otra mitad, que es exactamente la peor forma de hacerlo, porque el proyecto queda a medio camino entre dos modelos que no encajan. Esta lección separa esas dos mitades desde el principio y propone una ruta que las aborda en el orden correcto, con la red puesta y sin pedirte que apagues los tipos por el camino.

El inventario: tres clases de rotura

No todos los cambios cuestan lo mismo. Los primeros son renombres puros: el concepto es idéntico y solo cambia la palabra, de modo que un reemplazo cuidadoso basta.

La segunda clase, los cambios de forma, exige leer cada punto: no basta con cambiar la palabra porque también cambia la estructura del dato o el momento en que se obtiene. La tercera clase, las desapariciones, obliga a rediseñar el fragmento afectado; son pocas, pero son las que consumen el tiempo real de la migración.

La traducción central: del segundo argumento a setup

El cambio que aparece en cada fichero es el mismo, y una vez visto un par de veces se hace mecánico. El primer argumento de la v4 pierde schema y tsTypes; el segundo argumento se disuelve dentro de setup repartido en sus casilleros; y services se convierte en actors.

// ANTES: v4
const maquina = createMachine(
  {
    schema: { context: {} as Ctx, events: {} as Ev },
    tsTypes: {} as import('./maquina.typegen').Typegen0,
    initial: 'inactivo',
    states: {
      inactivo: { on: { IR: { target: 'cargando', cond: 'puedeCargar' } } },
      cargando: {
        invoke: { src: 'traer', onDone: { actions: 'guardar' }, onError: 'fallo' },
      },
      fallo: {},
    },
  },
  {
    actions: { guardar: assign({ datos: (_, e) => e.data }) },
    guards: { puedeCargar: (c) => c.permitido },
    services: { traer: (c) => fetch(`/api/${c.id}`).then((r) => r.json()) },
  },
)

// DESPUES: v5
const maquina = setup({
  types: { context: {} as Ctx, events: {} as Ev },
  actions: { guardar: assign({ datos: ({ event }) => event.output }) },
  guards: { puedeCargar: ({ context }) => context.permitido },
  actors: {
    traer: fromPromise(async ({ input }: { input: { id: string } }) => {
      const r = await fetch(`/api/${input.id}`)
      return r.json()
    }),
  },
}).createMachine({
  initial: 'inactivo',
  states: {
    inactivo: { on: { IR: { target: 'cargando', guard: 'puedeCargar' } } },
    cargando: {
      invoke: {
        src: 'traer',
        input: ({ context }) => ({ id: context.id }),
        onDone: { actions: 'guardar' },
        onError: 'fallo',
      },
    },
    fallo: {},
  },
})

Fíjate en el detalle que más sorprende al migrar: el servicio de la v4 leía el context directamente, mientras que el actor de la v5 recibe un input explícito. No es burocracia; es lo que permite que el actor sea reutilizable fuera de esta máquina y lo que hace verificable el contrato de entrada, tal como vimos en la lección anterior. Si te encuentras escribiendo un input que copia el context entero, casi siempre significa que el actor está haciendo demasiado.

La ruta en seis pasos y el orden que la hace segura

Antes de tocar una línea, pon la red. Los tests basados en el modelo son ideales aquí porque se derivan del propio grafo: si generas los caminos con @xstate/graph sobre la máquina de v4 y guardas las secuencias de eventos y los estados esperados, tendrás un oráculo que sobrevive a la migración y que detecta cualquier cambio de comportamiento que los renombres hayan introducido sin querer.

flowchart TD
P0[paso 0: red de tests desde el grafo] --> P1[paso 1: subir xstate y su integracion a la vez]
P1 --> P2[paso 2: renombres mecanicos]
P2 --> P3[paso 3: borrar tsTypes y la CLI de typegen]
P3 --> P4[paso 4: adoptar setup maquina a maquina]
P4 --> P5[paso 5: estrechar el error unknown]
P5 --> P6[paso 6: adoptar lo nuevo: params y enqueueActions]
style P0 fill:#a6e3a1,color:#11111b
style P4 fill:#cba6f7,color:#11111b
style P6 fill:#89b4fa,color:#11111b

El orden importa más que la velocidad. Los renombres van antes que setup porque son verificables uno a uno y dejan la aplicación arrancando. El borrado del typegen va antes que la adopción de setup porque mantener ambos a la vez produce errores contradictorios difíciles de leer. Y las capacidades nuevas —parámetros, enqueueActions, spawnChild, emit— van al final, porque mezclarlas con la migración impide saber si un fallo viene del cambio de versión o del rediseño que acabas de introducir.

Queda la pregunta táctica: cómo dividir el trabajo en un proyecto grande. La respuesta es un alias de paquete, que permite instalar ambas versiones a la vez y migrar por partes.

{
  "dependencies": {
    "xstate": "^5.0.0",
    "xstate4": "npm:xstate@^4.38.0"
  }
}

Con las dos instaladas, cada módulo importa la versión que le toca y la migración deja de ser un salto de todo o nada. Pero hay una restricción que decide cómo trocear: una máquina de v5 no puede invocar como actor a una máquina de v4, ni al revés, porque el protocolo del actor cambió. La unidad de migración, por tanto, no es el fichero sino el ÁRBOL DE ACTORES: una máquina y todos sus hijos, nietos y descendientes se migran juntos, y la frontera entre versiones solo puede pasar por donde ya hay una frontera de aplicación —un componente de React, un módulo de servicio—, nunca por dentro de una jerarquía de actores.