XState

Use this skill for any work that touches XState, Stately tooling, or @xstate/store, and for designing explicit state machines in TypeScript apps. Target stable XState v5 (xstate@5.33.x) unless the repo pins something else.

Workflow

1. Inspect the local setup before changing code:
   • Versions of xstate, @xstate/react (or vue/svelte/solid), @xstate/store and its adapter, @statelyai/inspect, TypeScript, and the framework.
   • Stale v4 signals: interpret(, Machine(, cond:, services:, tsTypes, schema:, predictableActionArguments, send( action creator, withConfig, state.nextEvents. If you find them, read migration.md before editing.
   • Where machines live, how actors are created (module scope, component hook, context provider, per request), and how implementations are injected (setup vs .provide).
   • Existing tests, inspection setup, and persistence of snapshots.
2. Refresh versions and docs when behavior matters. Start from source-map.md. When docs and package source disagree, trust the source and changelog.
3. Before you write a new machine, model it. Follow modeling.md: list behaviors, find the finite states, events, hierarchy, parallel regions, then context, actions, and actors. Write the state list and event list down (in chat or in a code comment) before the code.
4. Route to the focused reference: