The Complete Production SOP: How to Deploy and Run XState v5 Actor Model & Finite State Machines in Autonomous AI Agents

---
name: "xstate-v5-actor-state-machines"
description: "Model complex multi-step application logic and UI flows with mathematical state machines."
metadata:
  author: "Stately"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "create xstate v5 machine"
  - "xstate guards and actions"
  - "useActorRef react xstate"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noImplicitAny": true,
    "isolatedModules": true,
    "skipLibCheck": true
  }
}

import { setup, assign, fromPromise } from 'xstate';

interface CheckoutContext {
  cartId: string;
  shippingAddress: string | null;
  paymentToken: string | null;
  errorMessage: string | null;
}

type CheckoutEvent =
  | { type: 'SET_SHIPPING'; address: string }
  | { type: 'SUBMIT_PAYMENT'; token: string }
  | { type: 'RETRY' };

export const checkoutMachine = setup({
  types: {
    context: {} as CheckoutContext,
    events: {} as CheckoutEvent,
  },
  actors: {
    processPayment: fromPromise(async ({ input }: { input: { token: string } }) => {
      const res = await fetch('/api/pay', {
        method: 'POST',
        body: JSON.stringify(input),
      });
      if (!res.ok) throw new Error('Payment capture failed');
      return res.json();
    }),
  },
  guards: {
    hasValidShipping: ({ context }) => Boolean(context.shippingAddress),
  },
  actions: {
    recordShipping: assign({
      shippingAddress: ({ event }) => (event.type === 'SET_SHIPPING' ? event.address : null),
    }),
  },
}).createMachine({
  id: 'checkout',
  initial: 'shipping',
  context: {
    cartId: 'cart_123',
    shippingAddress: null,
    paymentToken: null,
    errorMessage: null,
  },
  states: {
    shipping: {
      on: {
        SET_SHIPPING: {
          target: 'payment',
          actions: 'recordShipping',
        },
      },
    },
    payment: {
      on: {
        SUBMIT_PAYMENT: {
          guard: 'hasValidShipping',
          target: 'processing',
        },
      },
    },
    processing: {
      invoke: {
        src: 'processPayment',
        input: ({ context }) => ({ token: context.paymentToken! }),
        onDone: { target: 'completed' },
        onError: {
          target: 'payment',
          actions: assign({
            errorMessage: ({ event }) => (event.error as Error).message,
          }),
        },
      },
    },
    completed: {
      type: 'final',
    },
  },
});

import { describe, it, expect } from 'vitest';
import { createActor } from 'xstate';
import { checkoutMachine } from './checkoutMachine';

describe('checkoutMachine', () => {
  it('transitions from shipping to payment upon SET_SHIPPING', () => {
    const actor = createActor(checkoutMachine).start();
    expect(actor.getSnapshot().value).toBe('shipping');

    actor.send({ type: 'SET_SHIPPING', address: '123 Market St' });
    expect(actor.getSnapshot().value).toBe('payment');
    expect(actor.getSnapshot().context.shippingAddress).toBe('123 Market St');
  });
});