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.

Prefer video? Watch our Migration to XState V5 beta webinar on YouTube.

I’m starting a new project. Should I use XState V5?

XState version 5 is in beta, and compared to XState version 4, it is feature complete with all the features of V4 and more. But as V5 is still in beta, some slight breaking changes may occur with future beta versions. So go ahead, but proceed with caution!

Creating machines and actors

Use createMachine(), not Machine()

Breaking change

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

XState v5 beta

import { createMachine } from 'xstate';

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

XState v4

// ❌ DEPRECATED
import { Machine } from 'xstate';

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

Use createActor(), not interpret()

Breaking change

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

XState v5 beta

import { createMachine, createActor } from 'xstate';

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

// ✅
const actor = createActor(machine);

XState v4

import { createMachine, interpret } from 'xstate';

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

// ❌ DEPRECATED
const actor = interpret(machine);

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

Breaking change

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

XState v5 beta

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

XState v4

// ❌ DEPRECATED
const specificMachine = machine.withConfig({
  actions: {
    /* ... */
  },
  guards: {
    /* ... */
  },
  services: {
    /* ... */
  },
  // ...
});

Set context with input, not machine.withContext()

Breaking change

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

XState v5 beta

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

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

XState v4

// ❌ DEPRECATED
const machine = createMachine({
  context: {
    actualMoney: 0,
  },
});

const moneyMachine = machine.withContext({
  actualMoney: 1000,
});

Actions ordered by default, predictableActionArguments no longer needed

Breaking change

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.

XState v5 beta

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

XState v4

// ❌ DEPRECATED
const machine = createMachine({
  predictableActionArguments: true,
  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

Breaking change

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

XState v5 beta

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

XState v4

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

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

Breaking change

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.

XState v5 beta

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

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

XState v4

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

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

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

actor.send() no longer accepts string types

Breaking change

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

XState v5 beta

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

XState v4

// ❌ DEPRECATED
actor.send('someEvent');

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

state.can() no longer accepts string types

Breaking change

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

XState v5 beta

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

XState v4

// ❌ DEPRECATED
state.can('someEvent');

Guarded transitions use guard, not cond

Breaking change

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

XState v5 beta

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

XState v4

// ❌ DEPRECATED
const machine = createMachine({
  on: {
    someEvent: {
      // renamed to `guard` in v5
      cond: 'someGuard',
      target: 'someState',
    },
  },
});

Use params to pass custom event data

Breaking change

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

XState v5 beta

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

XState v4

// ❌ DEPRECATED
const machine = createMachine({
  entry: {
    type: 'greet',
    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

Breaking change

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

XState v5 beta

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

XState v4

// ❌ DEPRECATED
const machine = createMachine({
  strict: true,
  on: {
    knownEvent: {
      // ...
    },
  },
});

Use explicit eventless (always) transitions

Breaking change

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:

XState v5 beta

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

XState v4

// ❌ DEPRECATED
const machine = createMachine({
  // ...
  states: {
    someState: {
      on: {
        '': {
          target: 'anotherState',
        },
      },
    },
  },
});

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

Use reenter: true, not internal: false

Breaking change

internal: false is now reenter: true

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

XState v5 beta

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

XState v4

// ❌ DEPRECATED
const machine = createMachine({
  // ...
  on: {
    someEvent: {
      target: 'sameState',
      internal: false,
    },
  },
});

Transitions are internal by default, not external

Breaking change

All transitions are implicitly internal. This change is relevant for transitions defined on compound state nodes with entry or exit actions, invoked actors, or delayed transitions (after). If you relied on implicit re-entering of a compound state node, use reenter: true:

XState v5 beta

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

XState v4

// ❌ DEPRECATED
const machine = createMachine({
  // ...
  states: {
    compoundState: {
      entry: 'someAction',
      on: {
        someEvent: {
          // implicitly external
          target: 'compoundState.childState', // non-relative target
        },
      },
      initial: 'childState',
      states: {
        childState: {},
      },
    },
  },
})

XState v5 beta

// ✅
const machine = createMachine({
  // ...
  states: {
    compoundState: {
      after: {
        1000: {
          target: 'compoundState.childState',
          reenter: true, // make it external explicitly!
        }
      },
      initial: 'childState',
      states: {
        childState: {},
      },
    },
  },
})

XState v4

// ❌ DEPRECATED
const machine = createMachine({
  // ...
  states: {
    compoundState: {
      after: {
        1000: {
          // implicitly external
          target: 'compoundState.childState', // non-relative target
        }
      },
      initial: 'childState',
      states: {
        childState: {},
      },
    },
  },
})

Child state nodes are always re-entered

Breaking change

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:

XState v5 beta

// ✅

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

XState v4

// ❌ DEPRECATED

const machine = createMachine({
  // ...
  states: {
    compoundState: {
      on: {
        someEvent: {
          target: '.childState', // implicitly internal, childState not re-entered
        },
      },
      initial: 'childState',
      states: {
        childState: {
          entry: 'someAction',
        },
      },
    },
  },
})

Use stateIn() to validate state transitions, not in

Breaking change

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

XState v5 beta

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

XState v4

// ❌ DEPRECATED
const machine = createMachine({
  on: {
    someEvent: {
      in: '#someMachine.form.submitting'
      target: 'someState',
    },
  },
});

Use actor.subscribe() instead of state.history

Breaking change

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

XState v5 beta

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

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

XState v4

// ❌ DEPRECATED
actor.subscribe((state) => {
  doSomeComparison(state.history, state);
});

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

Actors

Use actor logic creators for invoke.src instead of functions

Breaking change

The available actor logic creators are:

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

See Actors for more information.

XState v5 beta

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

XState v4

// ❌ DEPRECATED
import { createMachine } from 'xstate';

const machine = createMachine({
  invoke: {
    src: (context) => async () => {
      const data = await getData(context.userId);

      // ...
      return data;
    },
  },
});

XState v5 beta

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

const machine = createMachine({
  invoke: {
    src: fromCallback(({ sendBack, receive, input }) => {
      // ...
    }),
    input: ({ context, event }) => ({
      userId: context.userId,
    }),
  },
});

XState v4

// ❌ DEPRECATED
import { createMachine } from 'xstate';

const machine = createMachine({
  invoke: {
    src: (context, event) => (sendBack, receive) => {
      // context.userId
      // ...
    },
  },
});

XState v5 beta

// ✅
import { fromEventObservable, createMachine } from 'xstate';
import { interval, mapTo } from 'rxjs';

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

XState v4

// ❌ DEPRECATED
import { createMachine } from 'xstate';
import { interval, mapTo } from 'rxjs';

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

Use actors property on options object instead of services

Breaking change

services have been renamed to actors:

XState v5 beta

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

XState v4

// ❌ DEPRECATED
const specificMachine = machine.withConfig({
  actions: {
    /* ... */
  },
  guards: {
    /* ... */
  },
  services: {
    /* ... */
  },
  // ...
});

Use subscribe() for changes, not onTransition()

Breaking change

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

XState v5 beta

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

XState v4

// ❌ DEPRECATED
const actor = interpret(machine);
actor.onTransition((state) => {
  // ...
});

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

Breaking change

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

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

XState v5 beta

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

XState v4

// ❌ DEPRECATED
const actor = interpret(machine);
actor.start(someState);

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

Breaking change

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

XState v5 beta

// ✅
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
});

XState v4

// ❌ DEPRECATED
const actor = interpret(machine);
actor.start();

actor.subscribe((state) => {
  // Current snapshot immediately emitted
});

Loop over events instead of using actor.batch()

Breaking change

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

XState v5 beta

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

XState v4

// ❌ DEPRECATED
actor.batch(events);

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

TypeScript

Use types instead of schema

Breaking change

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

XState v5 beta

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

XState v4

// ❌ DEPRECATED
const machine = createMachine({
  schema: {} as {
    context: {
      /* ...*/
    };
    events: {
      /* ...*/
    };
  },
});

Use types.typegen instead of tsTypes

Breaking change

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

XState v5 beta

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

XState v4

// ❌ DEPRECATED
const machine = createMachine({
  tsTypes: {};
  schema: {} as {
    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.