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:

Actor Type	Creator	Use Case
State Machine	createMachine()	Complex state logic with transitions
Promise	fromPromise()	Async operations (fetch, timers)
Callback	fromCallback()	Bidirectional streams (WebSocket, EventSource)
Observable	fromObservable()	RxJS streams
Transition	fromTransition()	Reducer-like state updates

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)

v4 (WRONG)	v5 (CORRECT)
createMachine() alone	setup().createMachine()
interpret()	createActor()
service.start()	actor.start()
state.matches()	snapshot.matches()
services: {}	actors: {}
state.context	snapshot.context

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

Level	Focus
Beginner	Counter, toggle machines; setup() pattern
Intermediate	Guards, actions, hierarchical states, fromPromise()
Advanced	Observable actors, spawning, actor orchestration

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