Skip to content
Version: XState v5

Migrating from XState v4 to v5

The guide below explains how to migrate from XState version 4 to version 5. Migrating from XState v4 to v5 should be a straightforward process. If you get stuck or have any questions, please reach out to the Stately team on our Discord.

This guide is for developers who want to update their codebase from v4 to v5 and should also be valuable for any developers wanting to know the differences between v4 and v5.

XState v5 and TypeScript​

XState v5 and its related libraries are written in TypeScript, and utilize complex types to provide the best type safety and inference possible for you. XState v5 requires TypeScript version 5.0 or greater. For best results, use the latest TypeScript version.

Follow these guidelines to ensure that your TypeScript project is ready to use XState v5:

  • Use the latest version of TypeScript, version 5.0 or greater (required)

    npm install typescript@latest --save-dev

  • Set strictNullChecks to true in your tsconfig.json file. This will ensure that our types work correctly and will also help catch errors in your code (strongly recommended)

    // tsconfig.json
    {
      compilerOptions: {
        // ...
        strictNullChecks: true,
        // or set `strict` to true, which includes `strictNullChecks`
        // "strict": true
      },
    }

  • Set skipLibCheck to true in your tsconfig.json file (recommended)

Creating machines and actors​

Use createMachine(), not Machine()​

The Machine(config) function is now called createMachine(config):

import { createMachine } from 'xstate';

const machine = createMachine({
  // ...
});

Use createActor(), not interpret()​

The interpret() function has been renamed to createActor():

import { createMachine, createActor } from 'xstate';

const machine = createMachine(/* ... */);

// ✅
const actor = createActor(machine, {
  // actor options
});

Use machine.provide(), not machine.withConfig()​

The machine.withConfig() method has been renamed to machine.provide():

// ✅
const specificMachine = machine.provide({
  actions: {
    /* ... */
  },
  guards: {
    /* ... */
  },
  actors: {
    /* ... */
  },
  // ...
});

Set context with input, not machine.withContext()​

The machine.withContext(...) method can no longer be used, as context can no longer be overridden directly. Use input instead:

// ✅
const machine = createMachine({
  context: ({ input }) => ({
    actualMoney: Math.min(input.money, 42),
  }),
});

const actor = createActor(machine, {
  input: {
    money: 1000,
  },
});

Actions ordered by default, predictableActionArguments no longer needed​

Actions are now in predictable order by default, so the predictableActionArguments flag is no longer required. Assign actions will always run in the order they are defined.

// ✅
const machine = createMachine({
  entry: [
    ({ context }) => {
      console.log(context.count); // 0
    },
    assign({ count: 1 }),
    ({ context }) => {
      console.log(context.count); // 1
    },
    assign({ count: 2 }),
    ({ context }) => {
      console.log(context.count); // 2
    },
  ],
});

The spawn() function has been removed​

Instead of using the imported spawn() function to create actors inside assign(...) actions:

  • Use the spawnChild(...) action creator (preferred)
  • Or use the spawn(...) method from the first argument passed to the assigner function inside of assign(...) actions (useful if you need the actor ref in context)

Read the documentation on spawning actors for more information.

// ✅
import { spawnChild, assign } from 'xstate';

// Spawning a direct child:
const machine1 = createMachine({
  // ...
  entry: spawnChild('someChildLogic', {
    id: 'someChild',
  }),
});

// Spawning a child with the actor ref in `context`:
const machine2 = createMachine({
  // ...
  entry: assign({
    child: ({ spawn }) => spawn('someChildLogic'),
  }),
});

Use getNextSnapshot(…) instead of machine.transition(…)​

The machine.transition(…) method now requires an "actor scope" for the 3rd argument, which is internally created by createActor(…). Instead, use getNextSnapshot(…) to get the next snapshot from some actor logic based on the current snapshot and event:

// ✅
import {
  createMachine,
  getNextSnapshot,
} from 'xstate';

const machine = createMachine({
  // ...
});

const nextState = getNextSnapshot(
  machine,
  machine.resolveState({ value: 'green' }),
  { type: 'timer' },
);

nextState.value; // yellow

Send events explictly instead of using autoForward​

The autoForward property on invoke configs has been removed. Instead, send events explicitly.

In general, it's not recommended to forward all events to an actor. Instead, only forward the specific events that the actor needs.

// ✅
const machine = createMachine({
  // ...
  invoke: {
    src: 'someSource',
    id: 'someId',
  },
  always: {
    // Forward events to the invoked actor
    // This will not cause an infinite loop in XState v5
    actions: sendTo('someId', ({ event }) => event),
  },
});

States​

Use state.getMeta() instead of state.meta​

The state.meta property has been renamed to state.getMeta():

// ✅
state.getMeta();

The state.toStrings() method has been removed​

import { type StateValue } from 'xstate';

export function getStateValueStrings(stateValue: StateValue): string[] {
  if (typeof stateValue === 'string') {
    return [stateValue];
  }
  const valueKeys = Object.keys(stateValue);

  return valueKeys.concat(
    ...valueKeys.map((key) =>
      getStateValueStrings(stateValue[key]!).map((s) => key + '.' + s),
    ),
  );
}

// ...

const stateValueStrings = getStateValueStrings(stateValue);
// e.g. ['green', 'yellow', 'red', 'red.walk', 'red.wait', …]

Use state._nodes instead of state.configuration​

The state.configuration property has been renamed to state._nodes:

// ✅
state._nodes;

Read events from inspection API instead of state.events​

The state.events property has been removed, because events are not part of state, unless you explicitly add them to the state's context. Use the inspection API to observe events instead, or add the event explicitly to the state's context:

// ✅
import { createActor } from 'xstate';
import { someMachine } from './someMachine';

const actor = createActor(someMachine, {
inspect: (inspEvent) => {
if (inspEvent.type === '@xstate.event') {
console.log(inspEvent.event);
}
}
});

Events and transitions​

Implementation functions receive a single argument​

Implementation functions now take in a single argument: an object with context, event, and other properties.

// ✅
const machine = createMachine({
  entry: ({ context, event }) => {
    // ...
  },
});

send() is removed; use raise() or sendTo()​

The send(...) action creator is removed. Use raise(...) for sending events to self or sendTo(...) for sending events to other actors instead.

Read the documentation on the sendTo action and raise action for more information.

// ✅
const machine = createMachine({
  // ...
  entry: [
    // Send an event to self
    raise({ type: 'someEvent' }),

    // Send an event to another actor
    sendTo('someActor', { type: 'someEvent' }),
  ],
});

Pre-migration tip: Update v4 projects to use sendTo or raise instead of send.

Use enqueueActions() instead of pure() and choose()​

The pure() and choose() methods have been removed. Use enqueueActions() instead.

For pure() actions:

// ✅
entry: [
  enqueueActions(({ context, event, enqueue }) => {
    enqueue('action1');
    enqueue('action2');
  }),
];

For choose() actions:

// ✅
entry: [
  enqueueActions(({ enqueue, check }) => {
    if (check('someGuard')) {
      enqueue('action1');
      enqueue('action2');
    }
  }),
];

actor.send() no longer accepts string types​

String event types can no longer be sent to, e.g., actor.send(event); you must send an event object instead:

// ✅
actor.send({ type: 'someEvent' });

Pre-migration tip: Update v4 projects to pass an object to .send().

state.can() no longer accepts string types​

String event types can no longer be sent to, e.g., state.can(event); you must send an event object instead:

// ✅
state.can({ type: 'someEvent' });

Guarded transitions use guard, not cond​

The cond transition property for guarded transitions is now called guard:

// ✅
const machine = createMachine({
  on: {
    someEvent: {
      guard: 'someGuard',
      target: 'someState',
    },
  },
});

Use params to pass params to actions & guards​

Properties other than type on action objects and guard objects should be nested under a params property; { type: 'someType', message: 'hello' } becomes { type: 'someType', params: { message: 'hello' }}. These params are then passed to the 2nd argument of the action or guard implementation:

// ✅
const machine = createMachine({
  entry: {
    type: 'greet',
    params: {
      message: 'Hello world',
    },
  },
  on: {
    someEvent: {
      guard: { type: 'isGreaterThan', params: { value: 42 } },
    },
  },
}).provide({
  actions: {
    greet: ({ context, event }, params) => {
      console.log(params.message); // 'Hello world'
    },
  },
  guards: {
    isGreaterThan: ({ context, event }, params) => {
      return event.value > params.value;
    },
  },
});

Pre-migration tip: Update action and guard objects on v4 projects to move properties (other than type) to a params object.

Use wildcard * transitions, not strict mode​

Strict mode is removed. If you want to throw on unhandled events, you should use a wildcard transition:

// ✅
const machine = createMachine({
  on: {
    knownEvent: {
      // ...
    },
    '*': {
      // unknown event
      actions: ({ event }) => {
        throw new Error(`Unknown event: ${event.type}`);
      },
    },
  },
});

const actor = createActor(machine);

actor.subscribe({
  error: (err) => {
    console.error(err);
  },
});

actor.start();

actor.send({ type: 'unknownEvent' });

Use explicit eventless (always) transitions​

Eventless (“always”) transitions must now be defined through the always: { ... } property of a state node; they can no longer be defined via an empty string:

// ✅
const machine = createMachine({
  // ...
  states: {
    someState: {
      always: {
        target: 'anotherState',
      },
    },
  },
});

Pre-migration tip: Update v4 projects to use always for eventless transitions.

Use reenter: true, not internal: false​

internal: false is now reenter: true

External transitions previously specified with internal: false are now specified with reenter: true:

// ✅
const machine = createMachine({
  // ...
  on: {
    someEvent: {
      target: 'sameState',
      reenter: true,
    },
  },
});

Transitions are internal by default, not external​

All transitions are internal by default. This change is relevant for transitions defined on state nodes with entry or exit actions, invoked actors, or delayed transitions (after). If you relied on the previous XState v4 behavior where transitions implicitly re-entered a state node, use reenter: true:

// ✅
const machine = createMachine({
  // ...
  states: {
    compoundState: {
      entry: 'someAction',
      on: {
        someEvent: {
          target: 'compoundState.childState',
          // Reenters the `compoundState` state,
          // just like an external transition
          reenter: true,
        },
        selfEvent: {
          target: 'childState',
          reenter: true,
        },
      },
      initial: 'childState',
      states: {
        childState: {},
      },
    },
  },
});
// ✅
const machine = createMachine({
  // ...
  states: {
    compoundState: {
      after: {
        1000: {
          target: 'compoundState.childState',
          reenter: true, // make it external explicitly!
        },
      },
      initial: 'childState',
      states: {
        childState: {},
      },
    },
  },
});

Child state nodes are always re-entered​

Child state nodes are always re-entered when they are targeted by transitions (both external and internal) defined on compound state nodes. This change is relevant only if a child state node has entry or exit actions, invoked actors, or delayed transitions (after). Add a stateIn guard to prevent undesirable re-entry of the child state:

// ✅

const machine = createMachine({
  // ...
  states: {
    compoundState: {
      on: {
        someEvent: {
          guard: not(stateIn({ compoundState: 'childState' })),
          target: '.childState',
        },
      },
      initial: 'childState',
      states: {
        childState: {
          entry: 'someAction',
        },
      },
    },
  },
});

Use stateIn() to validate state transitions, not in​

The in: 'someState' transition property is removed. Use guard: stateIn(...) instead:

// ✅
const machine = createMachine({
  on: {
    someEvent: {
      guard: stateIn({ form: 'submitting' }),
      target: 'someState',
    },
  },
});

Use actor.subscribe() instead of state.history​

The state.history property is removed. If you want the previous snapshot, you should maintain that via actor.subscribe(...) instead.

// ✅
let previousSnapshot = actor.getSnapshot();

actor.subscribe((snapshot) => {
  doSomeComparison(previousSnapshot, snapshot);
  previousSnapshot = snapshot;
});

Pre-migration tip: Update v4 projects to track history using actor.subscribe().

Actions can throw errors without escalate​

The escalate action creator is removed. In XState v5 actions can throw errors, and they will propagate as expected. Errors can be handled using an onError transition.

// ✅
const childMachine = createMachine({
  // This will be sent to the parent machine that invokes this child
  entry: () => {
    throw new Error('This is some error');
  },
});

const parentMachine = createMachine({
  invoke: {
    src: childMachine,
    onError: {
      actions: ({ context, event }) => {
        console.log(event.error);
        //  {
        //    type: ...,
        //    error: {
        //      message: 'This is some error'
        //    }
        //  }
      },
    },
  },
});

Actors​

Use actor logic creators for invoke.src instead of functions​

The available actor logic creators are:

  • createMachine
  • fromPromise
  • fromObservable
  • fromEventObservable
  • fromTransition
  • fromCallback

See Actors for more information.

// ✅
import { fromPromise, setup } from 'xstate';

const machine = setup({
  actors: {
    getUser: fromPromise(async ({ input }: { input: { userId: string } }) => {
      const data = await getData(input.userId);
      // ...
      return data;
    }),
  },
}).createMachine({
  invoke: {
    src: 'getUser',
    input: ({ context, event }) => ({
      userId: context.userId,
    }),
  },
});
// ✅
import { fromCallback, createMachine } from 'xstate';

const machine = createMachine({
  invoke: {
    src: fromCallback(({ sendBack, receive, input }) => {
      // ...
    }),
    input: ({ context, event }) => ({
      userId: context.userId,
    }),
  },
});
// ✅
import { fromEventObservable, createMachine } from 'xstate';
import { interval, mapTo } from 'rxjs';

const machine = createMachine({
  invoke: {
    src: fromEventObservable(() =>
      interval(1000).pipe(mapTo({ type: 'tick' })),
    ),
  },
});

Use invoke.input instead of invoke.data​

The invoke.data property is removed. If you want to provide context to invoked actors, use invoke.input:

// ✅
const someActor = createMachine({
  // The input must be consumed by the invoked actor:
  context: ({ input }) => input,
  // ...
});

const machine = createMachine({
  // ...
  invoke: {
    src: 'someActor',
    input: {
      value: 42,
    },
  },
});

Use output in final states instead of data​

To produce output data from a machine which reached its final state, use the top-level output property instead of data:

// ✅
const machine = createMachine({
  // ...
  states: {
    finished: {
      type: 'final',
    },
  },
  output: {
    answer: 42,
  },
});

To provide a dynamically generated output, replace invoke.data with invoke.output and add a top-level output property:

// ✅
const machine = createMachine({
  // ...
  states: {
    finished: {
      type: 'final',
      output: ({ event }) => ({
        answer: event.someValue,
      }),
    },
  },
  output: ({ event }) => event.output,
});

Don't use property mappers in input or output​

If you want to provide dynamic context to invoked actors, or produce dynamic output from final states, use a function instead of an object with property mappers.

// ✅
const machine = createMachine({
  // ...
  invoke: {
    src: 'someActor',
    input: ({ context, event }) => ({
      value: event.value,
    }),
  },
});

// The input must be consumed by the invoked actor:
const someActor = createMachine({
  // ...
  context: ({ input }) => input,
});

// Producing machine output
const machine = createMachine({
  // ...
  states: {
    finished: {
      type: 'final',
    },
  },
  output: ({ context, event }) => ({
    answer: context.value,
  }),
});

Use actors property on options object instead of services​

services have been renamed to actors:

// ✅
const specificMachine = machine.provide({
  actions: {
    /* ... */
  },
  guards: {
    /* ... */
  },
  actors: {
    /* ... */
  },
  // ...
});

Use subscribe() for changes, not onTransition()​

The actor.onTransition(...) method is removed. Use actor.subscribe(...) instead.

// ✅
const actor = createActor(machine);
actor.subscribe((state) => {
  // ...
});

createActor() (formerly interpret()) accepts a second argument to restore state​

interpret(machine).start(state) is now createActor(machine, { snapshot }).start()

To restore an actor at a specific state, you should now pass the state as the snapshot property of the options argument of createActor(logic, options). The actor.start() property no longer takes in a state argument.

// ✅
const actor = createActor(machine, { snapshot: someState });
actor.start();

Use actor.getSnapshot() to get actor’s state​

Subscribing to an actor (actor.subscribe(...)) after the actor has started will no longer emit the current snapshot immediately. Instead, read the current snapshot from actor.getSnapshot():

// ✅
const actor = createActor(machine);
actor.start();

const initialState = actor.getSnapshot();

actor.subscribe((state) => {
  // Snapshots from when the subscription was created
  // Will not emit the current snapshot until a transition happens
});

Loop over events instead of using actor.batch()​

The actor.batch([...]) method for batching events is removed.

// ✅
for (const event of events) {
  actor.send(event);
}

Pre-migration tip: Update v4 projects to loop over events to send them as a batch.

Use snapshot.status === 'done' instead of snapshot.done​

The snapshot.done property, which was previously in the snapshot object of state machine actors, is removed. Use snapshot.status === 'done' instead, which is available to all actors:

// ✅
const actor = createActor(machine);
actor.start();

actor.subscribe((snapshot) => {
  if (snapshot.status === 'done') {
    // ...
  }
});

state.nextEvents has been removed​

The state.nextEvents property is removed, since it is not a completely safe/reliable way of determining the next events that can be sent to the actor. If you want to get the next events according to the previous behavior, you can use this helper function:

import type { AnyMachineSnapshot } from 'xstate';

function getNextEvents(snapshot: AnyMachineSnapshot) {
  return [...new Set([...snapshot._nodes.flatMap((sn) => sn.ownEvents)])];
}

// Instead of `state.nextEvents`:
const nextEvents = getNextEvents(state);

TypeScript​

Use types instead of schema​

The machineConfig.schema property is renamed to machineConfig.types:

// ✅
const machine = createMachine({
  types: {} as {
    context: {
      /* ...*/
    };
    events: {
      /* ...*/
    };
  },
});

Use types.typegen instead of tsTypes​

The machineConfig.tsTypes property has been renamed and is now at machineConfig.types.typegen.

// ✅
const machine = createMachine({
  types: {} as {
    typegen: {};
    context: {
      /* ...*/
    };
    events: {
      /* ...*/
    };
  },
});

@xstate/react​

useInterpret() is now useActorRef()​

The useInterpret() hook, which is used to return an actorRef ("service" in XState v4), is renamed to useActorRef().

// ✅
import { useActorRef } from '@xstate/react';

const actorRef = useActorRef(machine); // or any other logic

useActor(logic) now accepts actor logic, not an actor​

The useActor(logic) hook now accepts actor logic (such as fromPromise(...), createMachine(...), etc.) instead of an existing ActorRef.

To use an existing ActorRef, use actor.send(...) to send events and useSelector(actor, ...) to get the snapshot:

// ✅
import { useSelector } from '@xstate/react';

function Component({ someActorRef }) {
  const state = useSelector(someActorRef, (s) => s);

  return <button onClick={() => someActorRef.send({ type: 'someEvent' })} />;
}

Use machine.provide() to provide implementations in hooks​

For dynamically creating machines with provided implementations, the useMachine(...), useActor(...), and useActorRef(...) hooks no longer accept:

  • Lazy machine creators as the 1st argument
  • Implementations passed to the 2nd argument

Instead, machine.provide(...) should be passed directly to the 1st argument.

The @xstate/react package considers machines with the same configuration to be the same machine, so it will minimize rerenders but still keep the provided implementations up-to-date.

// ✅
import { useMachine } from '@xstate/react';
import { someMachine } from './someMachine';

function Component(props) {
  const [state, send] = useMachine(
    someMachine.provide({
      actions: {
        doSomething: () => {
          props.onSomething?.(); // Kept up-to-date
        },
      },
    }),
  );

  // ...
}

@xstate/vue​

useMachine() now returns snapshot instead of state, and actor instead of service​

To keep consistent naming with the rest of XState and related libraries:

  • state is now snapshot
  • service is now actor
// ✅
import { useMachine } from '@xstate/vue';

// ...

const {
  snapshot, // Renamed from `state`
  send,
  actor, // Renamed from `service`
} = useMachine(someMachine);

New features​

Frequently asked questions​

When will Stately Studio be compatible with XState v5?​

We are currently working on Stately Studio compatibility with XState v5. Exporting to XState v5 (JavaScript or TypeScript) is already available. We are working on support for new XState v5 features, such as higher-order guards, partial event wildcards, and machine input/output.

Upvote or comment on Stately Studio + XState v5 compatibility in our roadmap to stay updated on our progress.

When will the XState VS Code extension be compatible with XState v5?​

The XState VS Code extension is not yet compatible with XState v5. The extension is a priority for us, and work is already underway.

Upvote or comment on XState v5 compatibility for VS Code extension in our roadmap to stay updated on our progress.

When will XState v5 have typegen?​

TypeScript inference has been greatly improved in XState v5. Especially with features like the setup() API and dynamic parameters, the main use-cases for typegen are no longer needed.

However, we recognize that there may still be some specific use-cases for typegen. Upvote or comment on Typegen for XState v5 in our roadmap to stay updated on our progress.

How can I use both XState v4 and v5?​

You can use both XState v4 and v5 in the same project, which is useful for incrementally migrating to XState v5. To use both, add "xstate5": "npm:xstate@5" to your package.json manually or through the CLI:

npm i xstate5@npm:xstate@5

Then, you can import the v5 version of XState in your code:

import { createMachine } from 'xstate5';
// or { createMachine as createMachine5 } from 'xstate5';

If you need to use different versions of an integration package, such as @xstate/react, you can use a similar strategy as above, but you will need to link to the correct version of XState in the integration package. This can be done by using a script:

npm i xstate5@npm:xstate@5 @xstate5/react@npm:@xstate/react@4 --force
// scripts/xstate5-react-script.js
const fs = require('fs-extra');
const path = require('path');

const rootNodeModules = path.join(__dirname, '..', 'node_modules');

fs.ensureSymlinkSync(
  path.join(rootNodeModules, 'xstate5'),
  path.join(rootNodeModules, '@xstate5', 'react', 'node_modules', 'xstate'),
);
// package.json
"scripts": {
  "postinstall": "node scripts/xstate5-react-script.js"
}

Then, you can use the XState v5 compatible version of @xstate/react in your code:

import { useMachine } from '@xstate5/react';
// or { useMachine as useMachine5 } from '@xstate5/react';
import { createMachine } from 'xstate5';
// or { createMachine as createMachine5 } from 'xstate5';

// ...