XState draws a line between a store and a state machine

An actor is the running copy of a machine definition

The building blocks are four words long: event-driven programming, state machines, statecharts, and the actor model. The first three describe how you write the logic. The fourth is what makes it run.

A machine definition and a running machine are two different things. createMachine takes a configuration object and returns the definition. createActor takes that definition and returns the running instance, described in the README as an instance of the machine logic, like a store. Events go into the actor, state comes back out through a subscription, and the definition itself stays inert.

The formalism underneath is not homegrown. The README points at the W3C SCXML specification as the inspiration. XState declares zero dependencies, and that claim covers the package you install from npm, not the editor or the studio wrapped around it.

@xstate/store is a separate library that shares the name

Not every application needs statecharts, and the project ships a second package for the ones that do not. @xstate/store is described as an extremely small event-based store with first-class TypeScript inference, similar to Redux or Zustand but with less boilerplate.

It installs on its own:

npm install @xstate/store

A store is a context object plus a map of event handlers. No states, no transitions and no actors appear anywhere in it:

import { createStore } from '@xstate/store';
const donutStore = createStore({
  context: {
    donuts: 0,
    favoriteFlavor: 'chocolate'
  },
  on: {
    addDonut: (context) => ({ ...context, donuts: context.donuts + 1 }),
    changeFlavor: (context, event: { flavor: string }) => ({
      ...context,
      favoriteFlavor: event.flavor
    })
  }
});

Every handler returns a whole new context object instead of mutating the old one, and changeFlavor types its own event inline as { flavor: string }, which is where the TypeScript inference claim comes from. The guidance is to start here if you just need a store and move to full machines when the logic turns out to need them. The README is also explicit that the two packages work well together and that you do not need one to use the other.

Four starter templates, all opening the same machine file

Getting to a running machine takes one command:

npm install xstate

Past that, the project points at four templates hosted on CodeSandbox and StackBlitz, and they read as a compatibility list. vanilla-ts is XState v5 with TypeScript and no framework at all. react-ts, vue-ts and svelte-ts add React, Vue and Svelte to the same three ingredients. All four open on the same file, feedbackMachine.ts, so what separates them is the binding layer and nothing else.

Framework bindings do exist as separate packages, such as @xstate/vue, @xstate/svelte and @xstate/solid in the release list. For the server side, the README says the same library is useful for backend application logic, and the examples directory carries express-workflow and mongodb-credit-check-api for exactly that shape of work.

Recent alpha releases target framework bindings

The release list says where the work is. The three most recent are @xstate/[email protected], @xstate/[email protected] and @xstate/[email protected], all dated 2026-11-02.

So the framework bindings are heading for new major versions, and none of the three is stable. The core xstate package is the one the four templates pin, at v5. The repository is not archived, its last push was on 2026-10-04, and the licence is MIT.

If you plan to depend on the framework bindings, those alpha tags are the thing to plan around. The @xstate/store README is where the main README sends you for React and Solid bindings, selectors and more, so the binding story is documented one package down rather than at the top.

preinstall runs ensure-pnpm, so npm install stops before it starts

The repository root is where the friction lives. package.json declares workspaces over packages/* and scripts/*, and its preinstall script runs node ./scripts/ensure-pnpm.js. Any install that is not pnpm is stopped before it does anything. postinstall then runs manypkg check and preconstruct dev, and build is preconstruct build.

The rest of the scripts show how much surface a contributor touches. Formatting is oxfmt, linting is oxlint with unused disable directives promoted to errors, typechecking is tsc, and tests run under vitest with one project per package: test:core is vitest run --project xstate, and test:store is vitest run --project @xstate/store*. Releases go through changesets, with changeset version and changeset publish as separate commands.

Author and licence sit in the same file: David Khourshid, MIT.

Twenty-four example directories, five carrying a 7guis prefix

The examples directory maps what XState is good at better than a feature list would. Five entries carry a 7guis prefix: 7guis-counter-react, 7guis-temperature-react, 7guis-flight-booker-react, and Vue versions of the counter and the temperature converter. Each is a small interactive problem where holding the state correctly is the entire difficulty.

The rest spread out. timer, stopwatch, snake-react and tiles are drawing and timing. todomvc-react and friends-list-react are the usual list-shaped demos. tic-tac-toe-react, store-tic-tac-toe and trivia-game-example are turn-taking, which is where a machine starts to earn its keep. Then the ones that are not toys at all: express-workflow, fetch, mongodb-credit-check-api, mongodb-persisted-state, persisted-donut-maker and workflow-accumulate-room-readings.

Alongside them the repository keeps four framework template directories and a migration.md at the root for moving between versions.

Redux is the honest comparison, Stately Studio is the visual half

The README does not pretend XState is the only way to hold application state. It calls @xstate/store similar in spirit to Redux and Zustand, and recommends that package for anyone who just needs a store. That is the comparison worth making, and the difference is one of shape rather than speed: a store maps events to a new context object, while a machine additionally gives you named states, entry actions, and somewhere to put effects and orchestration.

The visual half lives outside the package. Stately Studio is where you create, edit and collaborate on machines, export to many formats including XState v5, autogenerate tests and documentation, deploy to Stately Sky, and generate or modify machines with Stately AI. There is a separate Stately Editor, a VS Code extension, and state.new as a short path into the registry.

None of that is required to use the library. It is, though, where the project's visible effort sits, which matters when you decide how much of your own tooling you want routed through it.

Editorial conclusion

Reach for xstate when your logic has states worth naming, effects to run and transitions worth drawing. Reach for @xstate/store when all you need is events mapped to a new context object. Do not plan on npm install working inside the repository, since preinstall runs a pnpm check and stops anything else. Before pinning either package, read the release list: the newest framework binding tags, for @xstate/vue, @xstate/svelte and @xstate/solid, are alphas.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. statelyai/xstate on GitHub