XState v5 Skill

Name: xstate
Rating: 92
Author: seed-hypermedia

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

typescript

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)

typescript

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

code

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