| name | xstate |
| description | Design, implement, and review XState v5 state machines and @xstate/react integrations in TypeScript. Use when modeling finite workflows, async actors, statecharts, guarded transitions, delayed transitions, actor systems, or machine-driven React behavior.
|
| references | ["references/modeling.md","references/transitions.md","references/actors.md","references/promises.md","references/callbacks.md","references/observables.md","references/child-actors.md","references/react.md","references/testing.md"] |
XState
Use XState when the domain has meaningful modes, transitions, async lifecycle, cancellation, guards, delays, or actor boundaries. The goal is not "state management"; the goal is to make the process explicit, typed, inspectable, and hard to misuse.
Core Standard
- Prefer
setup({ types, actors, actions, guards, delays }).createMachine(...) for typed machines with named implementations.
- Put finite modes in states.
- Put durable facts in context.
- Put side effects behind actors, actions, guards, and delays.
- Put request data in
invoke.input.
- Put UI decisions on snapshots:
matches, hasTag, can, and selected context.
- Initialize each actor instance with
input.
- Define default implementations in
setup(...); replace runtime implementations with .provide(...).
- Model later external changes as keyed remounts, domain events, or subscription actors.
Reading Guide
Read only the references needed for the task:
- Modeling: states, state types, context, events, guards, tags, delays.
- Transitions: guarded, eventless, delayed, and pure transitions.
- Actors: async work, actor choice, invocation, outputs, cancellation.
- Promises:
fromPromise, request input, output, errors, abort signals.
- Callbacks: subscriptions, imperative APIs,
sendBack, receive, cleanup.
- Observables: observable snapshots and observable event streams.
- Child Actors:
invoke, spawn, spawnChild, child ownership, inspection.
- React:
@xstate/react, .provide(...), actor input, selectors.
- Testing: actor tests,
waitFor, provided implementations, timing.
Working Loop
- Name the process and its legal modes.
- Define the domain events.
- Decide what data survives transitions.
- Move effects into actors or named implementations.
- Connect UI through actor hooks and snapshot reads.
- Test behavior at the actor boundary.
