xstate

XState v5 Skill

CRITICAL: This skill covers XState v5 ONLY. Do not use v4 patterns, APIs, or documentation. XState v5 requires TypeScript 5.0+.

When to Use

• State machine and statechart design
• Actor system implementation
• XState v5 API usage (setup, createMachine, createActor)
• Framework integration (React, Vue, Svelte)
• Complex async flow orchestration

Key Concepts

Actors are independent entities that communicate by sending messages. XState v5 supports:

Quick Start

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

const machine = setup({
  types: {
    context: {} as { count: number },
    events: {} as { type: 'increment' } | { type: 'decrement' },
  },
  actions: {
    increment: assign({ count: ({ context }) => context.count + 1 }),
    decrement: assign({ count: ({ context }) => context.count - 1 }),
  },
}).createMachine({
  id: 'counter',
  initial: 'active',
  context: { count: 0 },
  states: {
    active: {
      on: {
        increment: { actions: 'increment' },
        decrement: { actions: 'decrement' },
      },
    },
  },
});

// Create and start actor
const actor = createActor(machine);
actor.subscribe((snapshot) => console.log(snapshot.context.count));
actor.start();
actor.send({ type: 'increment' });

v5 API Changes (NEVER use v4 patterns)

Invoke vs Spawn

• invoke: Actor lifecycle tied to state (created on entry, stopped on exit)
• spawn: Dynamic actors independent of state transitions

Inspection API (Debugging)

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

Event types: @xstate.actor, @xstate.event, @xstate.snapshot, @xstate.microstep

File Organization

feature/
├── feature.machine.ts    # Machine definition
├── feature.types.ts      # Shared types (optional)
├── feature.tsx           # React component
└── feature.test.ts       # Machine tests

Learning Path

Supporting Documentation

• PATTERNS.md - Guards, actions, actors, hierarchical/parallel states
• REACT.md - React hooks (useMachine, useActor, useSelector)
• EXAMPLES.md - Complete working examples

Resources

• Official Docs
• Stately Studio - Visual editor