# XState — State Machines & Statecharts for Complex Logic

> XState is a library for creating, interpreting, and executing finite state machines and statecharts. Model complex application logic declaratively with first-class TypeScript, React/Vue/Svelte bindings, and visual editor (Stately).

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
npm i xstate @xstate/react
```

```ts
import { setup } from "xstate";
import { useMachine } from "@xstate/react";

const toggleMachine = setup({}).createMachine({
  id: "toggle",
  initial: "inactive",
  states: {
    inactive: { on: { TOGGLE: "active" } },
    active: { on: { TOGGLE: "inactive" } },
  },
});

function Toggle() {
  const [state, send] = useMachine(toggleMachine);
  return (
    <button onClick={() => send({ type: "TOGGLE" })}>
      {state.value}
    </button>
  );
}
```

## Intro

XState is a library for creating, interpreting, and executing finite state machines and statecharts. Built by David Khourshid and the Stately team, it brings rigorous state modeling (SCXML-inspired) to JavaScript with full TypeScript support and a visual editor.

- **Repo**: https://github.com/statelyai/xstate
- **Stars**: 29K+
- **Language**: TypeScript
- **License**: MIT

## What XState Does

- **Finite state machines** — explicit states and transitions
- **Statecharts** — hierarchical, parallel, history states
- **Actors** — async, message-passing concurrency model
- **Visualizer** — Stately Studio for drag-and-drop editing
- **Guards & actions** — conditional transitions and side-effects
- **Delayed transitions** — timeouts without setTimeout juggling
- **Model-based testing** — auto-generate tests from machines

## Architecture

A machine is a pure object describing states, events, transitions, and effects. `createActor(machine)` spawns a running instance. Actors can spawn child actors, creating a hierarchy. Works in any JS runtime; bindings exist for React, Vue, Svelte, Solid.

## Self-Hosting

Client-side library. Stately Studio is a SaaS for visual editing (optional), but machines run anywhere.

## Key Features

- Statecharts with hierarchy & parallel states
- Actor model for concurrency
- Fully type-safe (v5 uses `setup()` for inference)
- Visual editor (Stately Studio)
- Test generator (@xstate/test)
- Framework-agnostic core
- Bindings for React, Vue, Svelte, Solid
- SCXML export

## Comparison

| Library | Paradigm | Complexity | Visual Tools |
|---|---|---|---|
| XState | Statecharts | Highest ceiling | Stately Studio |
| Zustand | Hooks store | Low | No |
| Redux | Reducers | Medium | Redux DevTools |
| MobX | Reactive | Medium | MobX DevTools |

## FAQ

**Q: When should I use XState?**
A: Complex UI flows (multi-step forms, payment flows, video players, collaborative editing). For simple global state, Zustand is enough.

**Q: What is the Actor model?**
A: A concurrency model where each actor is an independent state machine that communicates via messages, avoiding race conditions from shared state.

**Q: What changed in v5?**
A: v5 introduces a `setup()` API for better TS type inference, simplifies the actor system, and replaces `interpret` with `createActor`.

## Sources & Credits

- Docs: https://stately.ai/docs
- GitHub: https://github.com/statelyai/xstate
- License: MIT

---
Source: https://tokrepo.com/en/workflows/xstate-state-machines-statecharts-complex-logic-2f0e099f
Author: Script Depot