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