XState v5 Skill Skill | Agent Skills

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

Agent Skills: XState v5 Skill

Install this agent skill to your local

Skill Files