statelyai/xstate

State machines, statecharts, and actors for complex logic

Structural Verdict

How Data Flows Through the System

Events flow through state machines to produce new states, or through stores to update context. Framework integrations subscribe to these updates and trigger UI re-renders.

1. Event dispatch — Components send events to actors or stores via send() or store.send()
2. State transition — Core engine processes events through state machine logic or store reducers
3. State update — New state is computed and stored, observers are notified
4. UI reaction — Framework hooks receive updates and trigger component re-renders
5. Devtools inspection — Development tools receive state changes for debugging visualization

System Behavior

How the system actually operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

Feedback Loops

• State Machine Transitions (recursive, balancing) — Trigger: Event sent to actor. Action: Compute next state based on current state and event. Exit: Reaches final state or stopped.
• Store Updates (convergence, balancing) — Trigger: Store event sent. Action: Apply reducer to current context. Exit: Context stabilizes.
• UI Re-render Loop (polling, reinforcing) — Trigger: State change detected. Action: Framework hook updates component. Exit: State stops changing.

Delays & Async Processing

• WebSocket Message Delivery (async-processing, ~network latency) — Debugging events arrive with delay
• Framework Hook Updates (eventual-consistency, ~render cycle) — UI updates lag behind state changes slightly

Control Points

• Development Mode Check (env-var) — Controls: Whether devtools registration is active. Default: process.env.NODE_ENV
• Comparison Functions (runtime-toggle) — Controls: When components re-render based on state changes. Default: defaultCompare function

Package Structure

This monorepo contains 14 packages:

Technology Stack

Key Components

• createActor (function) — Creates and manages actor instances from state machine or logic definitions packages/core/src/createActor.ts
• fromTransition (function) — Creates actor logic from a simple transition function packages/core/src/actors/transition.ts
• useActor (hook) — React hook that subscribes to actor state changes and returns current state and send function packages/xstate-react/src/useActor.ts
• createStore (function) — Creates a reactive store for state management without state machines packages/xstate-store/src/store.ts
• immerAssign (function) — Immutable state updates using Immer's draft pattern for XState context packages/xstate-immer/src/index.ts
• registerService (function) — Registers actors with browser devtools for inspection and debugging packages/core/src/dev/index.ts
• inspect (function) — Server-side inspection setup for WebSocket-based debugging of state machines packages/xstate-inspect/src/server.ts
• useSelector (hook) — React hook for selecting specific values from actor state with optional comparison packages/xstate-react/src/useSelector.ts
• createAtom (function) — Creates reactive atomic values that can be subscribed to packages/xstate-store/src/atom.ts
• createActorContext (function) — Creates React context providers for sharing XState actors across component trees packages/xstate-react/src/createActorContext.ts

Configuration

pnpm-workspace.yaml (yaml)

• packages (array, unknown) — default: packages/*,scripts/*

Related Data Pipeline Repositories

Frequently Asked Questions

Analyzed on April 1, 2026 by CodeSea. Written by Karolina Sarna.