Skip to content
Version: XState v5

Migrating XState v4 to v5

Following our guide below, migrating from XState version 4 to version 5 should be straightforward. If you get stuck or have any questions, please reach out to the Stately team on our Discord.

This guide is for users 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.

Creating machines​

Use createMachine(), not Machine()​

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

import { createMachine } from 'xstate';

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

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 in this manner. Use input instead:

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

const actor = interpret(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
    },
  ],
});

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 }) => {
    // ...
  },
});

Use either raise() or sendTo(), not send()​

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.

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 custom event data​

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' }}:

// ✅
const machine = createMachine({
  entry: {
    type: 'greet',
    params: {
      message: 'Hello world',
    },
  },
});

Pre-migration tip: Update v4 projects to include a params object on event objects passed to .send().

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}`);
      },
    },
  },
});

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,
    },
  },
});

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().

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, createMachine } from 'xstate';

const machine = createMachine({
  invoke: {
    src: fromPromise(async ({ input }) => {
      const data = await getData(input.userId);
      // ...
      return data;
    }),
    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 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 = interpret(machine);
actor.subscribe((state) => {
  // ...
});

interpret() accepts a second argument to restore state​

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

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

// ✅
const actor = interpret(machine, { state: 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 = interpret(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.

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​

machineConfig.tsTypes has been renamed and is now nested as machineConfig.types.typegen:

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

New features​

List coming soon

Timeline​

XState V5 is in beta, so there’s still work to be done. We anticipate the tools will be fully compatible with XState V5 beta by summer/fall 2023, with XState V5 stable being released by the end of 2023.

When will XState V5 be out of beta?​

We hope to release XState V5 as a stable major release this year (2023) but can’t provide any exact estimates. The rough timeline is:

  1. Get early feedback on XState V5 beta (xstate@beta)
  2. Ensure all related packages (e.g. @xstate/react, @xstate/vue) are fully compatible with XState V5
  3. Support V5 in typegen, @xstate/inspect, and related tools
  4. Support V5 (importing & exporting) in Stately Studio
  5. Release candidates
  6. Release XState V5 stable

Upvote or comment on XState V5 in our roadmap to be the first to find out when V5 is released.

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) will happen soonest, followed by 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?​

Typegen automatically generates intelligent typings for XState and is not yet compatible with XState v5. We’re working on Typegen alongside the VS Code extension.

Upvote or comment on Typegen for XState V5 in our roadmap to stay updated on our progress.