Healthy — Healthy across all four use cases

• Last commit today
• 11 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 53% of recent commits

Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against dependency CVEs from deps.dev and OpenSSF Scorecard

XState is an event-driven state machine and actor orchestration library for JavaScript/TypeScript with zero dependencies. It implements SCXML-compliant statecharts to model complex application logic (UI flows, workflows, async coordination) as deterministic, visual state graphs that transition on discrete events. Core capability: define state machines in packages/core/src/createMachine.ts and spawn child actors that communicate via message passing through the Mailbox.ts system. Monorepo (Yarn workspaces) with packages/core containing the state machine engine (StateMachine.ts, StateNode.ts, createMachine.ts), action system (packages/core/src/actions/*), actor implementations (packages/core/src/actors/* for promises, callbacks, observables), and graph utilities for path analysis. packages/core/src/createActor.ts bootstraps actor instances; Mailbox.ts and system.ts handle message-passing concurrency.

LLM-derived; treat as a starting point, not verified fact.

Frontend and backend developers building complex applications that require predictable state management beyond simple Redux patterns—particularly teams using React, Vue, or vanilla JS who need to model multi-step workflows, form state machines, async orchestration, or cross-actor communication without prop drilling.

LLM-derived; treat as a starting point, not verified fact.

Highly mature and production-ready. XState is v5+ with extensive TypeScript support (2.1M+ TS lines), comprehensive test coverage via Vitest, active sponsorship via Open Collective, and a thriving Discord community. The monorepo structure with multiple packages (@xstate/store, xstate core) and official templates (React, Vanilla TS on CodeSandbox) indicates well-maintained active development.

Low risk for core adoption—zero external dependencies, MIT-licensed, and strong community backing. Main concerns: v5 introduced breaking changes from v4 (consult migration docs), and depth of SCXML specification knowledge required for advanced features like parallel states and hierarchical machines can steepen the learning curve. Single primary maintainer (David Khourshid) via the Stately org, though community is active.

LLM-derived; treat as a starting point, not verified fact.

Active v5 development with focus on simplified API, improved TypeScript inference, and actor model maturity. Changelog-driven via Changesets (changeset script), with ongoing work on @xstate/store (lightweight event-based store alternative), vscode extension integration, and Stately Studio visual editing alignment. Recent efforts visible in packages/core/src/setup.ts (modern machine definition) and inspection APIs (packages/core/src/inspection.ts).

LLM-derived; treat as a starting point, not verified fact.

git clone https://github.com/statelyai/xstate.git
cd xstate
pnpm install  # enforced via preinstall script (scripts/ensure-pnpm.js)
pnpm test:core  # run core package tests (vitest)
pnpm build  # preconstruct build

Daily commands:

pnpm test:core:watch          # watch-mode tests for core package
pnpm test:watch               # all package tests in watch mode
pnpm build                     # compile via preconstruct

No traditional dev server—this is a library. Use templates: codesandbox.io/p/devbox/github/statelyai/xstate/tree/main/templates/vanilla-ts or stackblitz link in README.

• packages/core/src/createMachine.ts — Entry point for defining state machines; all state machine definitions flow through this factory function.
• packages/core/src/StateMachine.ts — Core state machine implementation managing state transitions, event handling, and effect execution.
• packages/core/src/createActor.ts — Instantiates executable actors from machine definitions; bridges machine definition to runtime behavior.
• packages/core/src/StateNode.ts — Represents individual states within a machine tree; handles state hierarchy, transitions, and guards.
• packages/core/src/types.ts — TypeScript type definitions for all public APIs; essential for understanding contract between modules.
• packages/core/src/transition.ts — Computes next state from current state and event; core deterministic transition logic.
• packages/core/src/actions.ts — Side-effect system including assign, send, spawn, and custom actions executed during state changes.

• StateMachine (TypeScript class with StateNode hierarchy) — Holds machine definition tree (StateNodes), guards, and initial state.
  • Failure mode: Malformed or circular state definitions cause invalid machine at creation time.
• Actor (execution runtime) (Mailbox, event loop, action executors) — Executes state transitions, manages mailbox, spawns children, emits snapshots.
  • Failure mode: Unhandled errors in actions or guards cause actor to stop; error sent to parent.
• Transition logic (Guard functions, event matching, StateNode traversal) — Evaluates guards, selects target states, computes enabled actions from event.
  • Failure mode: Guard exceptions propagate; invalid target states caught at machine creation.
• Action executor (ActorScope injection, enqueueActions batch) — Executes side effects (assign, send, spawn, cancel) after state transition.
  • Failure mode: Action errors logged; can cause actor to stop if not handled.
• Mailbox (Event queue with deferred processing) — FIFO event queue preventing stack overflow and ensuring predictable message order.
  • Failure mode: Overflow on recursive sends (mitigation: mailbox processes in batches).
• Graph analyzer (DFS/BFS, adjacency list, path deduplication) — Traverses state space to generate paths, shortest routes, and test coverage models.
  • Failure mode: Unreachable states or infinite loops in graph traversal cause hangs.
• Framework integration layer (useEffect/watch subscriptions, snapshot state sync) — Bridges actor lifecycle to React/Vue/Solid reactivity (hooks, composables).
  • Failure mode: Subscription leaks or stale snapshots if cleanup not called on unmount.

• User code → createMachine() — Machine definition (states, events, guards, actions) flows in.
• createMachine() → StateMachine instance — Machine object with StateNode tree and metadata created.
• StateMachine → createActor() — Machine passed to factory for instantiation into executable actor.
• Event (send) → Mailbox → Transition — User event queued, then evaluated against current state for next state.
• Transition result → Action executor — Enabled actions unpacked and executed in order (assign, send, spawn, etc.).
• Action results → Snapshot emission — State, context, spawned actors packaged as snapshot and sent to subscribers.

Add a custom action

1. Define action type and parameters in your machine setup or inline. (packages/core/src/actions.ts)
2. Create action function that receives ActorScope and executes side effects. (packages/core/src/actions/assign.ts (reference implementation))
3. Use in machine definition via enqueueActions or direct action property. (packages/core/src/actions/enqueueActions.ts)

Add a new actor type

1. Implement actor logic function matching ActorLogic<Snapshot, Event> interface. (packages/core/src/types.ts)
2. Reference new actor in spawn() or spawnChild action with fromPromise/fromCallback pattern. (packages/core/src/spawn.ts)
3. Optionally add framework-specific bindings in xstate-react, xstate-solid, etc. (packages/xstate-react/src/useActor.ts (reference))

Add a framework integration

1. Create new package directory (e.g., packages/xstate-angular). (packages/xstate-react/src/useMachine.ts (reference implementation))
2. Implement core hooks/composables using createActor and subscription patterns. (packages/xstate-solid/src/useActor.ts (reference for subscription model))
3. Export public API matching framework conventions. (packages/xstate-react/src/index.ts (reference))

Add graph analysis or testing capability

1. Implement path generator or visitor function operating on graph representation. (packages/core/src/graph/pathGenerators.ts (reference))
2. Use graph utility functions to traverse edges and states. (packages/core/src/graph/utils.ts)
3. Export from graph index for external use. (packages/core/src/graph/index.ts)

• TypeScript — Provides compile-time type safety for complex state machine definitions and actor logic.
• Zero dependencies — Minimizes bundle size and distribution friction; pure JavaScript state management.
• Actor model — Enables modular, concurrent state machine composition without shared mutable state.
• SCXML-inspired syntax — Aligns with W3C statechart standard for broad interoperability and familiarity.
• Graph analysis utilities — Enables automated testing, coverage analysis, and visualization of state space.

• Synchronous transition execution by default

  • Why: Deterministic, predictable state changes without async ambiguity.
  • Consequence: Async side effects must be wrapped in spawned actors, adding boilerplate.

• Immutable snapshots, mutable context via assign()

  • Why: Balances update tracing with practical context mutation.
  • Consequence: Developers must be aware of assign() semantics; deep mutations can cause bugs.

• Monorepo with separate framework packages

  • Why: Reduces core bundle and allows framework-agnostic usage.
  • Consequence: Integration requires learning framework-specific hooks for each platform.

• Mailbox-based actor message queuing

  • Why: Prevents stack overflow in recursive event sends; FIFO processing order.
  • Consequence: Slightly higher memory overhead and latency vs. immediate dispatch.

• Real-time distributed consensus (local orchestration only)
• Persistence layer (must be implemented by user via assign/send actions)
• Built-in authentication or authorization
• Time-series or analytics (separate concern)

• Avg cyclomatic complexity: ~6 — Heavy use of recursive StateNode traversal, guard evaluation, and graph algorithms; moderate cyclomatic complexity from branching transition logic.
• Largest file: packages/core/src/StateMachine.ts (450 lines)
• Estimated quality issues: ~3 — Some error handling in actors is implicit; graph algorithms can loop indefinitely on malformed machines; framework integrations have subscription leak risk if cleanup not enforced.

• Unhandled promise rejections in spawned promise actors (High) — packages/core/src/actors/promise.ts: Spawned promise actors that reject without catch can silently fail; no error propagation to parent.
• Recursive event sends causing mailbox growth (Medium) — packages/core/src/Mailbox.ts: Machine sending events to itself in action logic can rapidly fill mailbox if not bounded.
• Guard functions with side effects (Medium) — packages/core/src/guards.ts: Guards are called multiple times per transition; embedding side effects causes unpredictable execution count.
• Forgetting to clean up spawned actors (Medium) — packages/core/src/actions/stopChild.ts: Long-lived machines can accumulate child actors if not explicitly stopped, causing memory leaks.

• packages/core/src/transition.ts (CPU-bound state tree traversal) — Evaluates all possible transitions for an event; O(N) where N = enabled state nodes.
• packages/core/src/graph/shortestPaths.ts (Combinatorial graph search) — BFS over full state graph for test coverage; exponential in state count for highly connected machines.
• packages/core/src/Mailbox.ts (Single-threaded event loop) — Synchronous event processing loop drains entire queue in single tick; large bursts can block.

pnpm required: scripts/ensure-pnpm.js enforces pnpm; npm/yarn will fail. preconstruct dev mode: postinstall runs preconstruct dev, which symlinks source—rebuilds required after edits in test scenarios. TypeScript strict mode: core uses strict flags; type inference is aggressive and may catch implicit any. Actor scope: actors do not auto-terminate child actors; explicit stopChild() action needed or they persist in system. Clock mocking: SimulatedClock.ts for testing; real timers are not mocked by default in actors created with createActor()—pass clock in options.

• Finite State Machine (FSM) — Core abstraction of XState—understanding states, transitions, and events is mandatory to use the library effectively
• Statechart (Harel Statechart) — XState extends FSMs with hierarchical states, parallel regions, and deferred actions per the Harel model—required for modeling complex workflows
• Actor Model — XState implements Erlang-like actor semantics (createActor(), message passing via Mailbox.ts, child spawning); essential for understanding concurrent orchestration
• SCXML (State Chart XML) — W3C standard that XState aims to implement; defines syntax and semantics for executable statecharts, directly influences machine definition API
• Guard Condition — XState guards in packages/core/src/guards.ts conditionally enable transitions based on context; critical for data-driven state logic
• Deferred Effects (enqueueActions) — XState queues side effects (assign, send, spawn) rather than executing immediately; enables atomic transitions and simplified testing via enqueueActions.ts
• Reachability Analysis & Graph Traversal — Tools in packages/core/src/graph/ compute all valid state paths and transitions for visualization, testing, and coverage validation

• redux/redux — Alternative state management library; XState complements Redux for complex orchestration where Redux alone feels rigid
• pmndrs/zustand — Lightweight alternative to Redux; @xstate/store competes/pairs with it, and both used together for hybrid simple-state + statechart patterns
• statelyai/stately-editor — Visual editor for XState machines; generates TypeScript machine definitions from drag-and-drop statechart diagrams (complementary tooling)
• microsoft/state-machine-cat — Statechart syntax and visualization compiler; alternative DSL but XState is more runtime-focused, not diagram-first
• scxml/scxml — SCXML specification reference (W3C standard); XState's design is directly inspired by SCXML and aims to implement subset of spec

• Add missing test coverage for packages/core/src/actions/emit.ts—it's exposed but lacks dedicated test file; check test patterns in assign.ts or send.ts.
• Document the setup() API in packages/core/src/setup.ts with JSDoc examples matching the migration guide—newer TypeScript inference is underdocumented vs. v4.
• Create a runnable example for the actor scope pattern in packages/core/src/graph/actorScope.ts in the examples directory—file exists but no demo shows how to introspect actor families.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub