
What’s new to XState and Stately for May 2022?

## Updates in XState

With a few updates to @xstate/react and @xstate/fsm last month, our headline release was the `waitFor()` helper function.

Read all the release notes and patch notes in the [XState GitHub repository releases](https://github.com/statelyai/xstate/releases).

### `waitFor()`

The new `waitFor(...)` helper function asynchronously waits for an actor’s emitted value to satisfy a predicate before a timeout.

Example usage:

```ts
import { waitFor } from 'xstate/lib/waitFor';

// ...
const loginService = interpret(loginMachine).start();

const loggedInState = await waitFor(loginService, state =>
  state.hasTag('loggedIn')
);

loggedInState.hasTag('loggedIn'); // true
```

### Updates in the @xstate/react package

The @xstate/react package contains utilities for using XState with React. Find out more in the [@xstate/react package readme](https://github.com/statelyai/xstate/tree/main/packages/xstate-react).

#### React 18

The @xstate/react package now accepts React 18 as a peer dependency, and we rewrote the implementation to use the `use-sync-external-store` package. The package uses a shim to keep compatibility with older versions of React, so there is no need to worry if you haven’t upgraded yet.

#### Subscribing to stopped interpreters

Subscribing to a stopped interpreter will now always immediately emit the interpreter’s state and call a completion callback.

### `asEffect` and `asLayoutEffect` removed

We have removed the `asEffect` and `asLayoutEffect` action creators. These action creators didn’t fit the React model well and had the potential to cause issues as their existence suggested that they might be easy to use.

If you want to execute actions at those exact times, you can either make a call directly from those effects or send events to the machine from those effects and execute explicit actions in response to said events.

### `useMachine` and `useService` with @xstate/fsm 

We changed the signatures of `useMachine` and `useService` integrating with @xstate/fsm to match their signatures with their related hooks integrating with XState. Both now only accept a single generic. `useMachine` accepts `TMachine`, and `useService` accepts `TService`.

### Updates in the @xstate/fsm package

@xstate/fsm is a minimal, 1kb implementation of XState for finite state machines. Find out more in the [@xstate/fsm package readme](https://github.com/statelyai/xstate/tree/main/packages/xstate-fsm).

#### `.start()`

When you call .start() without any argument, it now always starts from the machine’s initial state, matching the behavior of XState itself.

## More coming soon!

If you want to know more about what we’ve got planned, you can [check out our Roadmap](https://xstate.js.org/docs/roadmap/). Got any feedback, or want to suggest features? [Share your thoughts in the XState discussions](https://github.com/statelyai/xstate/discussions).

We’re also looking for your feedback on specific ideas in our [Stately RFCs (Requests for comment)](https://github.com/statelyai/rfcs).

Updates to XState, @xstate/react and @xstate/fsm in the last month.

What’s new in May 2022?


A few weeks ago we uploaded a new video to the [Stately YouTube channel](http://youtube.com/c/statelyai) showing how you can build basic video player functionality using XState and Stately tools. You can watch the video below or [use the chapter links](/#video-chapters) to jump to the chapter you want to watch.

<Youtube id="3wZBSeLxVEw" />

## Video chapters

- [0:00](https://www.youtube.com/watch?v=3wZBSeLxVEw&t=0s) What we want to build
- [2:52](https://www.youtube.com/watch?v=3wZBSeLxVEw&t=172s) Modeling the video player
- [9:43](https://www.youtube.com/watch?v=3wZBSeLxVEw&t=583s) Implementing the state machine
- [19:49](https://www.youtube.com/watch?v=3wZBSeLxVEw&t=1189s) Modeling with the visual editor
- [22:10](https://www.youtube.com/watch?v=3wZBSeLxVEw&t=1330s) Editing the state machine
- [25:05](https://www.youtube.com/watch?v=3wZBSeLxVEw&t=1505s) Editing the state machine in the visual editor

## We want your suggestions and feedback

Please let us know what we should demo for you! Share your feedback or suggestions in [our GitHub Discussions](https://github.com/statelyai/xstate/discussions), [our Discord](https://discord.gg/xstate) or [Twitter](https://twitter.com/statelyai).

A few weeks ago we uploaded a new video to the Stately YouTube channel showing how you can build basic video player functionality using XState and Stately tools.

Building a video player with XState and Stately tools


This week we’ve added [our Roadmap](https://xstate.js.org/docs/roadmap) to the XState documentation.

Many of you have requested a roadmap to help you determine if it’s the right time to integrate XState and Stately tools into your team’s workflow. We’ve added a simple Roadmap so you know what we’re currently working on and what features are coming up soon.

## Upcoming features

To give you an idea of what we’re working on, below are the features currently planned for April - June 2022.

### XState

- XState v5 Alpha

### Editor

- Billing and Teams
- Feature parity with XState
- Authentication bug fixes
- Welcome emails
- Inline editing
- Simulation mode
- Markdown descriptions
- Workflow creation

### Documentation

- Stately tools visibility
- Update and rework

## Please give us your feedback and suggestions

We prioritize features based on your feedback. Please let us know if you have feedback or suggestions in [our GitHub Discussions](https://github.com/statelyai/xstate/discussions), [our Discord](https://discord.gg/xstate) or on [Twitter](https://twitter.com/statelyai).



We’ve added a Roadmap to our Documentation, so you know what we’re currently working on and what features are coming up soon.

Introducing the new Stately Roadmap


We’re hiring for a frontend engineer, backend engineer, developer advocate and product designer at Stately. You can [check out the Careers at Stately page on Notion](https://statelyai.notion.site/Careers-at-Stately-db3d704abd8f41058e5361e5ab9c1098).

## About Stately

Stately is building **the visual future of software development.**

At Stately, we want to make app and business logic accessible to the entire team and eliminate barriers between development, design, and product to make it easier to build and maintain complex applications quickly and robustly.

We enable development teams to collaborate effectively on even the most complex logic and flows with visual tools and insightful services. Helping them speak a common language so that the specifications, designs, and code are always synchronized, up-to-date, and visually clear.

We’re building a team inspired to work on this mission to make software development better for everyone and practice what we preach, both inside Stately and everywhere else.

## Questions from our office hours  stream last week

During [our office hours live stream last week](https://www.youtube.com/watch?v=zYCnVkaUT3w), we answered questions about working with Stately. You can find the questions and links to the timecode with our responses below.

### About the job listings

- [What are the responsibilities of the product designer role?](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=826s)
- [What is the hiring process?](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=943s)
- [What is the definition of a senior developer? (And other roles)](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=1627s)
- [Is there a trial period?](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=1175s)

### About Stately

- [When was the company founded, and how are you financially sustainable?](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=1115s)
- [What exciting projects would you be working on at Stately?](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=705s)

### About the Stately team

- [How many people are on the Stately team?](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=1225s)
- [Should I apply if I feel underqualified? What would help me get the role in the future?](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=1313s)
- [How well can Stately support neurodivergent people?](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=1969s)

### About timezones and locations

- [Are these jobs remote? Yes!](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=806s)
- [Which timezones do Stately currently work within?](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=1753s)
- [Where are you folks based?](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=1802s)

### About the day-to-day at Stately

- [What does team collaboration look like at Stately?](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=1364s)
- [What is the work culture like from an insider perspective?](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=1845s)
- [Are there a lot of video calls at Stately?](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=1441s)
- [What is the balance of sync vs. async collaboration at Stately?](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=1508s)
- [What is a good day at Stately vs. a bad day at Stately?](https://www.youtube.com/watch?v=zYCnVkaUT3w&t=2029s)

We’re hiring for a frontend engineer, backend engineer, developer advocate and product designer at Stately.

Stately is hiring!


Happy Wednesday! Time for our first Editor Changelog blog, where we’ll talk about the new updates we’ve shipped in the editor.

## Snap To Elements

When you’re placing states and events in the canvas, you’ll now be able to snap them to surrounding elements.

Snapping is a hugely requested feature and should help make your charts neater and more legible.

<video src="/blog/snap-to-elements.mp4" controls />

So far, we’ve implemented snapping to the _center_ of elements only. We’re keen to [hear your feedback](https://github.com/statelyai/editor-feedback/issues) if you want more snapping!

## Right-click menu

You can now right-click events and states to perform actions including:

- Renaming states/events
- Making states the 'initial' state
- Adding guards
- Turning events into self-transitions

And many more.

<video src="/blog/context-menu-demo.mp4" controls />

## Visual update for events

We’ve streamlined the way our events look to make them more visually distinct from states. This new look keeps the focus on the arrow, the direction of travel, and the flow of the chart.

![Statechart depicting the states of a Matt machine. The states are displayed as large rectangles with slightly rounded corners and lighter grey backgrounds. The events are displayed as smaller pill-shaped rounded rectangles with darker grey backgrounds.](/blog/changelog-1-events.png)

## Improvements to VSCode output

We’ve massively improved the way we handle transition targets in VSCode. Instead of every transition having an ugly `#(machine).state1.state2`, the VSCode extension will now make the most idiomatic choice out of `targetState`, `.targetState`, or `targetState.child`.

```ts
const machine = createMachine({
  initial: "a",
  states: {
    a: {
      on: {
        EVENT: {
          // Before
          target: "#(machine).b",
        },
      },
    },
    b: {},
  },
});

const machine = createMachine({
  initial: "a",
  states: {
    a: {
      on: {
        EVENT: {
          // After
          target: "b",
        },
      },
    },
    b: {},
  },
});
```

As part of this work, we’ve also improved how we handle `internal` - you’ll now get proper warnings inside the visual editor when you use `internal` incorrectly.

## Other Improvements

We’ve been hard at work fixing bugs in the VSCode extension and the CLI. You can keep up to date with those changes in our [`xstate-tools`](https://github.com/statelyai/xstate-tools/releases) repo.


The Stately Editor changelog is where we discuss new features released to the Stately Editor beta.

Stately Changelog #1 - Snap To Elements


Last week we launched [the new Stately homepage](https://stately.ai), which we hope will make it easy to understand what Stately and XState are and help you convince your team to use state machines.

You can watch us talk about the new design and its implementation during [last week’s office hours](https://youtu.be/WoPCd4D--Gk?t=771). I’m particularly impressed by David’s SVG arrows!

And if you have any feedback about the homepage, please let us know on [our Discord](https://discord.gg/xstate). We always appreciate your thoughts.


Last week we launched the new Stately homepage, which we hope will make it easy to understand what Stately and XState are and help you convince your team to use state machines.

Introducing the new Stately homepage


If you use VSCodium, Coder, Gitpod or another editor with VSCode-compatible extensions, you can now [install the XState VSCode extension from the Open VSX Registry](https://open-vsx.org/extension/statelyai/stately-vscode).

We released our [XState VSCode extension](https://marketplace.visualstudio.com/items?itemName=statelyai.stately-vscode) a few weeks ago, which gives you visual editing, autocomplete, typegen and linting for XState. The same extension is now available for VSCodium, Coder and Gitpod, and any other editors with VSCode-compatible extensions through the Open VSX Registry.

We had many requests to distribute the extension on the Open VSX Registry. As a person who uses [VSCodium](https://vscodium.com) myself, it was exciting to install the extension from inside VSCodium.

1. Open the command palette in VSCodium with `shift` + `cmd/ctrl` + `p`.
2. Search for the **Install Extensions** command and hit enter to open the Extensions search.
3. Search for **XState** to find the XState VSCode extension and install the extension using the **Install** button.
4. Once you have installed the extension, you can find the extension commands by searching for **XState** in the command palette.

You can also [download the XState VSCode extension directly from the Open VSX Registry](https://open-vsx.org/extension/statelyai/stately-vscode).

Please give us your feedback and let us know if you encounter any issues in [our Discord](https://discord.gg/xstate) or [our xstate-tools repository](https://github.com/statelyai/xstate-tools/issues).

If you use VSCodium, Coder, Gitpod or another editor with VSCode-compatible extensions, you can now install the XState VSCode extension from the Open VSX Registry.

XState VSCode extension now available on the Open VSX Registry


Around a month ago, we released [TypeScript Typegen](/blog/introducing-typescript-typegen-for-xstate) - an enormous upgrade to the TypeScript experience for XState.

We’ve had a great response to it so far, but it’s only been available for VSCode users.

Until now. With our new XState CLI, **you can get Typegen from the command line**.

- Read the full documentation on the [`@xstate/cli` docs](https://xstate.js.org/docs/packages/xstate-cli).
- Check out [our updated TypeScript Typegen guide](https://xstate.js.org/docs/guides/typescript.html#typegen). 
- Find the code on the [@xstate/cli GitHub repo](https://github.com/statelyai/xstate-tools/tree/main/apps/cli).

## Installation

```bash
npm install @xstate/cli
```

OR

```bash
yarn add @xstate/cli
```

## Commands

### `xstate typegen <files>`

```bash
xstate typegen "src/**/*.tsx?"
```

Run the typegen against a glob of files. This will scan every targeted file and generate a typegen file accompanying it. It will also import the typegen into your file, as described in [our typegen documentation](https://xstate.js.org/docs/guides/typescript.html#typegen).

Ensure you wrap your glob in quotes so that it executes correctly. Otherwise, you’ll get unexpected results.

#### Options

```bash
xstate typegen "src/**/*.tsx?" --watch
```

Runs the task on a watch, monitoring for changed files and running the typegen script against them.

## The Future

We’re really excited about the CLI, and all the cool things it’ll enable. The typegen really is just the surface. If you’ve got ideas for what we could do with it, don’t hesitate to add a feature request to the [`xstate-tools` repo](https://github.com/statelyai/xstate-tools/issues).


Get ready to run XState’s typegen commands outside of VSCode in our all-new CLI.

Introducing: The XState CLI


Modelling using statecharts changed my career as a dev. Of all the state management solutions I’ve tried, it feels the most complete, logical and robust. Even if you don’t use them in your app’s code, statecharts let you break down complex features into states, events, services, actions and guards.

It took me a long time to get comfortable modelling with statecharts. Even when I’d learned all the terms, it took time to work out a step-by-step process for building statecharts from scratch.

Today, I’m going to share **an opinionated, step-by-step guide for building statecharts from scratch**. This process _works for me_, but it might not work for you. Feel free to tweak it as you go.

## What you’ll need

1. A pen and paper, or a digital notepad of some kind
2. A statechart builder, such as [our visual editor](https://stately.ai/editor) or an XState machine in our [XState visualizer](https://stately.ai/viz)
3. A clear idea of what you’re building. Maybe something you’ve implemented at work? You could also pick something from [XState Catalogue](https://xstate-catalogue.com).

I’ve also built this [process as a statechart](https://stately.ai/registry/editor/d24479eb-ac20-44ae-a7b7-c0910e6247ad) using our visual editor.

## 1. List all the possible events

The first step in this process is to work out all the events that can be received by your statechart. You can think of an event as ‘something that happens’ in your app. There are plenty of examples even on this page:

1. Press the escape key
2. Press the space bar
3. Select some text
4. Click on an image

You don’t need to list _all_ possible events that the user can perform. You only need to **list the events that your statechart cares about**. Here are some examples:

For a submit form:

- User changes the value of an input
- User submits form

For a spreadsheet:

- User clicks a cell on the spreadsheet
- User holds down the `shift`/`ctrl` key
- User presses `escape`
- User scrolls up or down

Seeing all the events in a big list may start giving you an idea of what is possible in your statechart. You might start thinking in terms of _sequences of events_ — i.e. `User changes input` -> `User submits form`. Write down any sequences that pop into your head, they’ll be useful later.

## 2. List all the possible tasks

Next, it’s important to consider the _tasks_ your app needs to perform. These tasks could be called ‘side effects’ — things that happen as a result of your statechart running. These could be as diverse as:

1. **Adding an item to a todo list (in local state)**
2. **Sending a request to the API to load some data**
3. **Focusing an input**
4. **Waiting for a video to load**
5. **Subscribing to something for updates** (perhaps via `window.addEventListener()`)

_NOTE: I’m using ‘tasks’ loosely. This isn’t an official term in the XState docs — but ‘services’ and ‘actions’ are._

Once you have a list of tasks, you need to divide them into two groups.

### 2a. Services

The first group is for services, tasks where you need to _do something when they finish_. I wrote a [longer guide about the distinction between actions and services here](/blog/should-this-be-an-action-or-a-service).

From our list above, these are services:

2. **Sending a request to the API to load some data**

We need to get something from the API, meaning that we need to wait until we receive the data. This task can also fail — if we’re having network trouble or the API method fails. That means we care whether it succeeds or fails.

4. **Waiting for a video to load**

Same as above — we need to wait for the video to be loaded, and we care if it fails to load.

5. **Subscribing to something for updates**

Here, it’s a little different — when you subscribe to something, you need to clean up the listener to prevent a memory leak. For instance:

```ts
const listener = () => {
  console.log("Hello!");
};

// Subscribe
window.addEventListener("focus", listener);

// Unsubscribe
window.removeEventListener("focus", listener);
```

Here, we care about the outcome because we need to _run something at the end of the process_ — i.e. unsubscribe from the listener.

#### Adding onDone/onError events

Service completions/errors are handled _as events_ in your statechart, meaning they’re on the same level as your user clicking buttons.

When you’ve got your list of services, note down two things:

For each service that we need to wait for it to complete, add a `serviceName.onDone` event to your list.

For each service that might reasonably be expected to error, add a `serviceName.onError` event to your list.

### 2b. Actions

The second group is for actions, tasks that you can ‘fire and forget’. Unlike services, the statechart forgets about actions as soon as they’re fired.

From our list above, these are actions:

1. **Adding an item to a todo list (in local state)**

Changes to local state are pretty much always fire-and-forget. The reason is that, since we manage the local state ourselves, updating it is instant. [XState’s assign action](https://xstate.js.org/docs/guides/context.html#assign-action) is a good example.

2. **Focusing an input**

Focusing an input, in the same vein, is fire-and-forget. We don’t care about the outcome, and it’s unlikely to fail.

## 3. Work out the very first state

Now that you know _what can happen_ (events) and _what can be done_ (actions & services) in your statechart, it’s time to start adding some states.

### 3a. Know your statechart’s lifecycle

It’s always easiest to start at the beginning. Before you add your first state, consider the moment that your statechart gets initiated. What causes your statechart to run? Some examples:

An **authentication** statechart, which manages the state for whether the user is logged in to a website or not. This would be started the _first moment_ the user clicks on to any page of your app, and finished when they close your app.

A **sign up form** statechart, which handles a user signing up to your app. This might be started when the user visits the `/sign-up` route, and stopped when they exit it.

### 3b. Write down your first state

Now that you know what your app looks like when your statechart gets initiated, it’s time to name its initial state. Consider what the statechart is doing at that time. It could be `Loading data`, or `Waiting for user to submit form`, or even just `Idle`, waiting for something to happen.

#### Dynamic initial states

Every statechart _must_ have an initial state, and it can’t be dynamic — it must be the same every time your statechart runs.

If you feel your statechart _does_ have more than one initial state (for instance it could start in two different modes) consider using a ‘checking’ state via an [eventless transition](https://xstate.js.org/docs/guides/transitions.html#eventless-always-transitions).

## 4. Build out the states

Now that you have your first state, you can start the process of building out the states. Every state represents a length of time, so consider _what is happening_ during that state.

### 4a. Work out if any tasks are running

Do you have any services running? If so, _invoke_ those services using [XState’s invoke property](https://xstate.js.org/docs/guides/communication.html#invoking-services).

Does an action need to happen when you enter or exit the state? If so, add it as an [entry or exit action](https://xstate.js.org/docs/guides/actions.html#actions).

Remember, the _statechart itself_ is also a state. We often call it the ‘root state’. This means that you can run services or listen to events for the _entire duration of your statechart_. You can also run entry actions when your statechart starts, and exit actions when it stops.

### 4b. Work out which events can happen in that state

Consider the period of time your state represents. Which events should _do_ something, and what should they do?

#### Events that change state

If an event results in:

1. A new service running
2. Something new appearing on screen
3. Other types of events becoming possible
4. A current service stopping

Then it might need to move to a new state. A great example is a **data fetcher**. Your app is in two distinct states:

- **Fetching data**: it doesn’t yet have the data, and the ‘fetch data’ service is running.
- **Showing data**: it has the data, and is showing it on screen. The ‘fetch data’ service has stopped.

If you have an event like this, draw out the new event and either create a new state, or make it target an existing one if needed.

#### Events that don’t change state

Sometimes, [events can be used to fire an action](https://xstate.js.org/docs/guides/actions.html#api) instead of changing state. A good example of this is when a form input changes, and you need to save the new value to local state.

This is called a [self-transition](https://xstate.js.org/docs/guides/transitions.html#self-transitions), where the event doesn’t change the state — the state transitions to itself.

#### Events that do nothing

It’s important to bear in mind that when your statechart is in a certain state, _only the events that you specify_ will be handled. In other words, any event you don’t specify will do _nothing_ when it’s sent to the statechart.

A classic example of this is a form. When you submit the form, you go to the ‘submitting’ state. It’s important that you don’t allow the ‘submit’ event to be received while in the ‘submitting’ state — otherwise the form might get sent twice!

## 5. Keep going!

Once you’ve figured out which actions/services are running in which states, and what all the events do, you’ve modelled your first state! You’ll likely have states which branch off your initial state — so go through those one-by-one and build them out.

You can also leave parts of your statechart unimplemented, and dive into building the frontend/actions/services before returning to modelling again.

I’ve found this approach really useful when getting to grips with what my app does. You can even use a statechart as an early validation tool to confirm that what you’re building is correct.

If you’ve got any more questions, do [join our Discord](https://discord.gg/invite/xstate) and ask in the ‘modelling-help’ channel.


Stately dev Matt Pocock takes you through a step-by-step guide on modelling statecharts

Modelling 101: How to build a statechart from scratch


We’re excited to announce the public beta of the Stately Editor! The Stately Editor is a tool for creating and editing state diagrams. We’ve received a lot of great feedback from the private beta testers, and now we’re delighted to share it with everyone.

**[Try the Stately Editor beta now](https://stately.ai/editor?source=blog)**

![Visualize your application logic with the Stately Editor](./images/stately-editor-public-beta.png)

The software development lifecycle today is a bit fragmented. It’s very difficult for user stories, designs, code, tests, and documentation to stay in sync, leading to parts going out-of-date or even missing entirely. Bugs increase, and adding or modifying features becomes increasingly complex. And even understanding all the features and use-cases of an app becomes a daunting task.

Our mission is to **make app logic accessible to the entire team**, including developers, designers, and stakeholders. Using state machines and statecharts as a common visual language, the software development cycle becomes more collaborative, eliminating handoff and tightening the feedback loop.

The Stately Editor aims to be that collaborative visual app logic tool. Before, developers could build state machines and statecharts in code using [XState](https://github.com/statelyai/xstate). Now, you can create those same state diagrams visually.

And yes, it goes both ways: edit the code and see the updated state diagram. Edit the state diagram and see the updated code in real-time. All this is possible with the [XState VS Code extension](https://marketplace.visualstudio.com/items?itemName=statelyai.stately-vscode).

## Features

The editor supports everything you need to build state machines and statecharts:

- Atomic, compound, parallel, history, and final states
- Normal, guarded, and delayed events/transitions
- Entry, exit, and transition actions
- Invocations
- Done and error transitions for states and invocations
- State and event descriptions

There are currently two modes:

- **Editor mode**: add, modify, and delete states, events, and transitions, as well as data like actions, descriptions, and invocations.
- **Simulation mode**: run the statechart, trigger events, and see the active state nodes.

You can also **export machines to JSON**, ready to be used in your codebase with XState.

## Roadmap

We have a long list of features planned for the editor, including:

- Parameterized actions, guards, and invocations
- Built-in actions, such as `assign` and `raise`
- Schema editing for `context` and `events`
- More granular simulation control, such as specifying event payload and simulating delays
- Visualizing systems of actors, including spawned and invoked machines
- Warnings and errors for invalid machine definitions
- Customizable state node, event, and transition colors
- Rich text editing and content for state descriptions
- Markdown generation
- Event recording and playback
- Machine versioning and diffing
- Autolayout and smart layout controls
- Teams and private machines/systems
- _And so much more._

## Join the public beta

Excited to see what the Stately Editor can do? [Join the public beta by registering for free](https://stately.ai/registry?source=blog) and [create your first machine](https://stately.ai/editor?source=blog), or [discover other people’s machines](https://stately.ai/registry/discover?source=blog) and get inspired.

Please [let us know](https://github.com/statelyai/editor-feedback/issues/new) if you have any feedback, feature requests or bug reports.

<Announcement cta="Try the beta" href="https://stately.ai/editor?source=blog">
  Try the Stately Editor beta and start modeling your app logic visually.
</Announcement>

## Next steps

The editor is the initial state towards making the ultimate collaborative tool for visually editing even the most complex app logic. We’re excited to share the Stately Editor with the world, and we’re looking forward to hearing your reactions.

[Join our Discord community](https://discord.gg/xstate) to get help, ask questions, and give us your feedback.


We’re excited to announce the public beta of the Stately Editor! The Stately Editor is a tool for creating and editing state diagrams. We’ve received a lot of great feedback from the private beta testers, and now we’re delighted to share it with everyone.

Stately Editor public beta


<div
  style={{
    position: "relative",
    height: "0px",
    paddingBottom: "56.25%",
  }}
>
  <iframe
    src="https://www.loom.com/embed/1f90a1a454c7495ea755f044c394c54d"
    frameBorder="0"
    allowFullScreen
    style={{
      position: "absolute",
      top: 0,
      left: 0,
      width: "100%",
      height: "100%",
    }}
  ></iframe>
</div>

**XState and TypeScript are a match made in heaven**. TypeScript gives you type safety, and XState gives you logical safety. Together, they give you confidence that your code will do what you expect.

However, we’ve been hearing from the community for some time that the _experience_ of using TypeScript with XState needed improving.

Today's your lucky day. **XState’s TypeScript experience just got an _enormous_ upgrade**.

We have brought type generation into XState v4.29.0, and we’re aiming for **perfect types on all parts of XState’s API**.

We’re releasing typegen today as an opt-in beta. Be sure to check out the [known limitations](https://xstate.js.org/docs/guides/typescript.html#known-limitations) section of the docs.

## Getting Started

You can visit the [official docs](https://xstate.js.org/docs/guides/typescript.html#typegen) for the full guide, or follow the instructions:

1. Download and install the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=statelyai.stately-vscode).

2. Open a new file and create a new machine, passing the schema attributes:

```ts
import { createMachine } from "xstate";

const machine = createMachine({
  schema: {
    context: {} as { value: string },
    events: {} as { type: "FOO"; value: string } | { type: "BAR" },
  },
  initial: "a",
  states: {
    a: {
      on: {
        FOO: {
          actions: "consoleLogValue",
          target: "b",
        },
      },
    },
    b: {
      entry: "consoleLogValueAgain",
    },
  },
});
```

3. Add `tsTypes: {}` to the machine and save the file:

```diff
const machine = createMachine({
+ tsTypes: {},
  schema: {
    context: {} as { value: string },
    events: {} as { type: "FOO"; value: string } | { type: "BAR" },
  },
  initial: "a",
  states: {
    /* ... */
  },
});
```

4. The extension should automatically add a generic to the machine:

```ts
const machine = createMachine({
  // This generic just got added!
  tsTypes: {} as import("./filename.typegen").Typegen0,
  /* ... */
});
```

5. Add a second parameter into the `createMachine` call - this is where you implement the actions, services, guards and delays for the machine.

```ts
const machine = createMachine(
  {
    /* ... */
  },
  {
    actions: {
      consoleLogValue: (context, event) => {
        // Wow! event is typed to { type: 'FOO' }
        console.log(event.value);
      },
      consoleLogValueAgain: (context, event) => {
        // Wow! event is typed to { type: 'FOO' }
        console.log(event.value);
      },
    },
  }
);
```

## Typing improvements

Let’s get into the nitty-gritty and show you exactly what’s improved.

### Events in machine options

One of the most common pain points we heard from our community was using named actions, services and guards with TypeScript. The main reason is that you needed to write code like this:

```ts
createMachine(
  {
    schema: {
      events: {} as { type: "FOO"; value: string } | { type: "BAR" },
    },
    on: {
      FOO: {
        actions: "myAction",
      },
    },
  },
  {
    actions: {
      myAction: (context, event) => {
        /**
         * TS don't know if the event is FOO or BAR,
         * so we have to defensively check here
         */
        if (event.type === "FOO") {
          /**
           * Now we know that event.value
           * is present on FOO, because
           * we checked
           */
          console.log(event.value);
        }
      },
    },
  }
);
```

The VS Code extension **statically analyzes your machine**, and knows which events lead to which actions.

```ts
createMachine(
  {
    /* config */
  },
  {
    actions: {
      myAction: (context, event) => {
        /**
         * No more defensive check needed! event
         * is typed to only the events that cause
         * the action
         */
        console.log(event.value);
      },
    },
  }
);
```

This works for actions, services, guards and delays. It even works for **entry actions**, another big pain point from the community.

We’re hoping this lets you cut hundreds of lines of useless defensive code.

### Autocomplete on machine options

Another thing we’ve been hearing from the community is that it’s easy to make typos on machine options.

Now, with typegen, you get **autocomplete on all machine options**. The following code will error:

```ts
createMachine(
  {
    entry: ["sayHello"],
  },
  {
    actions: {
      /*
       * This will error, because sayhello does not
       * exist in the machine declaration above
       */
      sayhello: () => {},
    },
  }
);
```

We’ve also made it so any _missing_ machine options will error when
you implement them later. So, in a React component:

```tsx
const machine = createMachine({
  entry: ["sayHello"],
});

const App = () => {
  /**
   * This will error, because you haven't implemented
   * sayHello in your actions object
   */
  const [state, send] = useMachine(machine);
};
```

That gives you 100% confidence that your machine has all the things it needs to work.

### Typing of promise-services

Using promise-based services might be the single biggest pain point with XState and TypeScript. We used to have an entire troubleshooting section in our docs dedicated to them.

Now, you can **strongly type the results of promise-based services**. Here’s how:

```ts
createMachine(
  {
    schema: {
      /**
       * Pass the 'services' attribute to schema,
       * with all the names of your services and
       * the data they return
       */
      services: {} as {
        myService: {
          // The data that gets returned from the service
          data: { id: string };
        };
      },
    },
    invoke: {
      src: "myService",
      onDone: {
        actions: "consoleLogId",
      },
    },
  },
  {
    services: {
      /**
       * This service will now type error if it
       * returns anything other than { id: string }
       */
      myService: async () => {
        return {
          id: "1",
        };
      },
    },
    actions: {
      consoleLogId: (context, event) => {
        /**
         * This event now knows that it will
         * receive a data attribute with { id: string }
         */
        console.log(event.data.id);
      },
    },
  }
);
```

This makes handling data return types in XState intuitive, easy and type-safe.

## Acknowledgements

I want to thank my Stately colleague [Andarist](https://twitter.com/AndaristRake). His TypeScript wizardry, incredible attention to detail and deep love of open source helped make this possible. We’ve literally been talking about this for 18 months - and it’s finally here.


XState’s TypeScript experience just got an enormous upgrade - Typescript typegen, integrated with VS Code.

Introducing: TypeScript typegen for XState


Last week we asked our community, “What are the biggest benefits you’ve had from using state machines?”

At Stately, we’re obviously fans of state machines. Still, we wanted to ask our community the benefits they’ve experienced, whether they were working on a specific project or incorporating state machines into their everyday workflow.

## Reusability

Nowadays, so much of tech is component-oriented, so it was fascinating to hear from Martin that he reused the same state machines across different frameworks.

<Tweet id="1469042301783654417" />

> I think that **the biggest benefit comes from being able to use the same state machine across different frameworks**. With XState, even if you just use React on your projects, you can share your state machine with your [insert framework name here] friends.

## Maintaining complex app logic

<Tweet id="1468992722686017540" />

Pat’s blog post goes into fascinating depth on his work with Crucible. The section on XState starts with Pat’s realization that he needed a state machine and ends with him moving much of their application logic into statecharts.

> **We didn't start Crucible using XState but by the end of the project it was one of our most valuable tools…**
>
> …
>
> I was still new to statecharts and sort of overwhelmed by the whole idea so I needed to find a small feature I could prototype XState with where it would make sense and add recognizable value to a flow/process that could use more structure to it…
>
> …
>
> I built out the flow based on the services’ state and UI state, I defined all the valid transitions and where they’d go, I wired up the inputs/outputs to it, and then I turned it loose on matchmaking in an actual client and it worked beautifully.
>
> **I could look at the statechart and see the entire flow through the states**, I could see every valid transition that the statechart could take and where it would go, I could paste it into the XState visualizer and actually see a DIAGRAM OF ALL THE STATES AND WALK THROUGH THEM INTERACTIVELY.

[Read all of Pat’s post on his blog](https://tivac.com/2020/10/19/crucible-rip/).

## Maintainability

Maintainability is a popular feature of state machines, and Joshua is a fan.

<Tweet id="1468958231028326419" />

Matt’s article on ‘[useState vs useReducer vs XState - Part 1: Modals](/blog/usestate-vs-usereducer-vs-xstate-part-1-modals)’ shares examples of these different approaches and their maintainability. And he followed it up with his [React Finland talk, ‘Make legacy code delightful with statecharts’](https://www.youtube.com/watch?v=zll9uDQOOq0).

## Getting to the core of your logic

The [discussion on our Discord](https://discord.com/channels/795785288994652170/795785288994652174/918546073268670534) focused on mindset and how state machines can help us better understand our app logic. Jan got the conversation started.

> Certainly for me it must be that **it allows me to very quickly get to the essence and core behaviour of what I'm building**. Playing with boxes and arrows allow me to not get caught up in implementation details while figuring out how I want stuff to work.
>
> Afterwards, implementing actions and services just feels like filling in the blanks. Likewise hooking the machine up with my component is equally trivial: throw some `state.hasTag`, `state.context` and `send` in there, and you’ve got a stew going

And Steve continued.

> State machines make complex behaviors tractable; they help you think about the problem.
>
> State machines reveal complexities in ostensibly simple behaviors; they make you think about the problem.
>
> Yin and yang. Good cop, bad cop. **Thinking about your application behavior as a set of state machines focuses your mind on what's really going on inside that tangled mass of behaviors**.

## Robustness

Horacio also explained how the robustness of apps built with state machines could give us more faith in our work.

> Programming is all about confidence, and for me, **working with state machines gives me the same confidence on my code as writing tests**, with the addition to have a visual representation of my system that I can discuss, show and modify with all my teammates.
>
> Also having the confidence of refactoring code without the fear of breaking other parts of my app!!
>
> Definitely XState is one of my top additions of 2021 to my dev toolbelt! 💪

That’s just what we like to hear!

Thank you, everyone, for your responses. We love to hear about how you’re using state machines in your projects. If you’ve got any feedback you want to share with the Stately team, you can [find us on Twitter](https://twitter.com/statelyai) and join the community on [our Discord server](https://discord.gg).

_Note: quotes have been minimally edited to add emphasis and clarity._


At Stately we’re fans of state machines, but we wanted to ask our community… what are the benefits that you’ve experienced from using state machines?

What are the biggest benefits you’ve had from using state machines?


Last week our question of the week was “_how do you convince your teammates to use XState?_”

One of our most frequent requests for the documentation is more advice on how to convince others to use XState. Many people [read an article](https://dev.to/mpocock1/how-to-manage-global-state-with-xstate-and-react-3if5), [watch a talk](https://www.youtube.com/watch?v=9k1ZHHJWt7k) or [participate in a workshop](https://frontendmasters.com/courses/xstate/) about XState and are sold on using XState themselves. But when it comes to getting their team on board, they often need more.

Thanks to all the wonderful folks who answered our question [posted to Twitter](https://twitter.com/statelyai/status/1446035499777462274) and in our #office-hours [Discord](https://discord.gg/xstate) channel, we’ve got some fantastic suggestions.

## Present using the Visualizer

Many people immediately understand the benefits of statecharts as they’re familiar with diagrams using “boxes and arrows.” The Visualizer gives you an instant, recognisable overview of your application logic, which is often enough to get them on board.

<Tweet id="1446237663535714304" />

<Tweet id="1446087845073113092" />

## Give examples using their own work

Nick Hehr takes it step-by-step, utilizing the Visualizer.

<Tweet id="1446092594338017280" />

<Tweet id="1446062078264020994" />

And Farzad successfully convinced his team. We discussed his success in [our office hours last week](https://www.youtube.com/watch?v=GCWZ-froHKo).

## Give them side-by-side examples

Amy Pellegrini recommended many complementary approaches, starting with comparing XState to other types of state management.

<Tweet id="1446419479483793411" />

This might be an intensive approach, but it’s the ultimate way to show the benefits of XState.

## Show existing projects that are using XState

We’re all more convinced by a technology when we know it’s already being used by projects or organisations whose work we admire. Amy Pellegrini suggests taking advantage of that:

<Tweet id="1446420841219215372" />

## Dictate the use as team lead

A few people are fortunate enough to be leading their teams, and of course adoption is much easier when you can just tell your team to use XState from the top.

[Cédric](https://discord.com/channels/795785288994652170/895591583586598943/895730595378913390):

> I have said: "We will use XState" 😂

<Tweet id="1446084841259274240" />

## Become the expert so you can answer their questions and help them progress

But not everyone can be the boss. Amy Pellegrini recommends becoming the XState subject matter expert, so you’re better prepared to support the rest of your team.

<Tweet id="1446421516334387203" />

And Josh Ferrell suggests collaborating with your product team, showing them how to model with the Visualizer, enabling them to do the modeling themselves in the future.

<Tweet id="1446152427187572738" />

## Tell them that the Stately team is fast and responsive

Knowing a technology is under frequent development, and the developers are likely to respond to your feedback, is important to most of us when we’re embedding a new tool into a key part of our workflow. [Cédric on our Discord](https://discord.com/channels/795785288994652170/895591583586598943/895738949635551273) uses this as a way to convince his team to work with XState.

> Xstate team improve the project really quickly, office hours give a good idea of the roadmap and features, when something is propose there are a real discussion and project improvement from only “an idea” on discord

Thanks Cédric!

## Promoting the collaboration benefits

At Stately, we’re excited about the potential for collaboration with our Visualizer and Editor. We want to shrink the space between planning, design and development, helping the whole team work together on their application logic. [Cédric agrees with those benefits](https://discord.com/channels/795785288994652170/895591583586598943/895738949635551273).

> The Viz is a real support to share business logic between product and tech team, this could be add[ed] into a specifications and of course with the futur[e] way to create machine by a simple drag and drop this offer[s] the possibility for the product team to create themselves a real machine useful [for] the tech team

## Timing it right with a good use case for the team

On our Discord, [Jan has a carefully planned approach](https://discord.com/channels/795785288994652170/895591583586598943/895754626689814578):

> I received the task to build some pretty complicated UI components, and I opted to build them with simple state machines, implemented as good ol' `switch`-based reducers. Since we're using Redux, this approach didn't alienate my team entirely, and so the seed had been planted.
>
> Fast-forward a bit, and we're currently rewriting some of the core of our application as a state machine (or something of a Frankenstein statechart), after receiving new requirements would make it completely unmaintainable if we had continued in the same tracks. We're still doing it with `switch` (with nested states, even!), which isn't optimal, but it's way better than where we came from.
>
> For now it does the job, but my plan is to note any pains which could easily be solved with XState, and propose a rewrite if/when the time is right. I figure it will be a much easier sell if my team is already somewhat familiar with the concepts of state machines, and we have a really good use-case on our hands.

Finding the right timing for your team is key for introducing any new technology.

## Make them less intimidated by the terminology

And sometimes a team is rightfully cautious of trying a technology that comes across as new. It’s all about how you frame it…

<Tweet id="1446153971219853314" />

😂

In the future we hope to provide more documentation and advice to help you convince your team to use XState. If you have any suggestions or requests, please [let us know on our Discord](https://discord.gg/xstate). We want to make our tools work for you.


Last week our question of the week was how do you convince your teammates to use XState? Here are some suggestions

How do you convince your teammates to use XState?

Statecharts are a visual language used to describe the states in a process.

You may have used similar diagrams in the past to design user flows, plan databases or map app architecture. Statecharts are another way of using boxes and arrows to represent flows, but with XState these flows are also executable code that can be used to control the logic in your applications.

This guide covers the basics of statecharts in a beginner-friendly way, including:

- [states](#states)
- [transitions and events](#transitions-and-events)
- [initial states](#initial-state)
- [final states](#final-state)
- [compound states](#compound-states)
- [parallel states](#parallel-states)
- [self-transitions](#self-transition)
- [planning statecharts](#planning-statecharts)
- [delayed transitions](#delayed-transitions)
- [actions](#actions)

## States

The _states_ are represented by rounded rectangle boxes. To draw a statechart for the process of a dog, there are two states that would first come to mind:



![](https://raw.githubusercontent.com/statelyai/xstate/d98d948a534b028f4af8b271eb431a8625ab5cb3/docs/guides/introduction-to-state-machines-and-statecharts/asleep-awake.svg)

A dog is always **asleep** or **awake**. The dog can’t be asleep and awake at the same time, and it’s impossible for the dog to be neither asleep nor awake. There’s only these two states, a precisely limited, _finite_ number of states.

## Transitions and events

How the dog goes between **asleep** and **awake** is through _transitions_, which are symbolised by an arrow pointing from one state to the next state in the process’s sequence.



![](https://raw.githubusercontent.com/statelyai/xstate/d98d948a534b028f4af8b271eb431a8625ab5cb3/docs/guides/introduction-to-state-machines-and-statecharts/transitions-events.svg)

A transition is caused by an _event_ that results in the change of state. Transitions are labelled with their events.

Transitions and events are _deterministic_. Deterministic means that each transition and event always points to the same next state, and always produces the same result from their given starting condition, every time the process is run. Dogs never **wake up** to become **asleep** or **fall asleep** to become **awake**.

This tiny dog process, with its two finite states and two transitions is a _Finite State Machine._ A state machine is used to describe the behavior of something. The machine describes the thing’s states and the transitions between those states. It’s a Finite State Machine because it has a finite number of states. (Sometimes abbreviated to FSM by folks who love jargon).

## Initial state

Any process that has states will have an _initial state_, the default state the process exists in until an event happens to change the process’s state.

The initial state is represented by a filled circle with an arrow pointing from the circle to the initial state.



![](https://raw.githubusercontent.com/statelyai/xstate/d98d948a534b028f4af8b271eb431a8625ab5cb3/docs/guides/introduction-to-state-machines-and-statecharts/initial-state.svg)

Using a statechart to describe the process of walking the dog, the initial state would be **waiting** to walk.

## Final state

Most processes with states will have a _final state_, the last state when the process is finished. The final state is represented by a double border on the state’s rounded rectangle box.

In the dog walking statechart, the final state would be **walk complete**.

![Dog walking statechart showing waiting state transitioning through the leave home event to the on a walk state, then transitioning through the arrive home event to the final state of walk complete.](https://raw.githubusercontent.com/statelyai/xstate/d98d948a534b028f4af8b271eb431a8625ab5cb3/docs/guides/introduction-to-state-machines-and-statecharts/final-state.svg)

## Compound states

A compound state is a state that can contain more states, also known as child states. These child states can only happen when the parent compound state is happening. Inside the **on a walk** state, there could be the child states of **walking**, **running** and **stopping to sniff good smells**.

A compound state is symbolised by a labelled rounded rectangle box that acts as a container for its child states.



![](https://raw.githubusercontent.com/statelyai/xstate/d98d948a534b028f4af8b271eb431a8625ab5cb3/docs/guides/introduction-to-state-machines-and-statecharts/compound-state.svg)

A compound state should also specify which child state is the initial state. In the **on a walk** compound state, the initial state is **walking**.

Compound states are what makes statecharts capable of handling more complexity than an everyday state machine.

### Atomic states

An atomic state is a state that doesn’t have any child states. **Waiting**, **walk complete**, **walking**, **running** and **stopping to sniff good smells** are all atomic states.

### Parallel states

A parallel state is a compound state where all of its child states, also known as regions, are active simultaneously. The regions are separated inside the compound state container by a dashed line.

Inside the **on a walk** compound state, there could be two regions. One region contains the dog’s activity child states of **walking**, **running** and **stopping to sniff good smells**, and the other region containing the dog’s tail states of **wagging** and **not wagging**. The dog can walk and wag its tail, run and wag its tail or stop and sniff while wagging its tail, it can also do any of these activities without wagging its tail.



![](https://raw.githubusercontent.com/statelyai/xstate/d98d948a534b028f4af8b271eb431a8625ab5cb3/docs/guides/introduction-to-state-machines-and-statecharts/parallel-states.svg)

Both regions should also specify which child state is the initial state. In our **tail** region, the initial state is **not wagging**.

### Self-transition

A self-transition is when an event happens, but the transition returns to the same state. The transition arrow exits and re-enters the same state.

A helpful way to describe a self-transition is “doing something, not going somewhere” in the process.

In a **dog begging** process, there would be a **begging** state with a **gets treat** event. And for the dogs who love their food, no matter how many times you go through the **gets treat** event, the dog returns to its **begging** state.



![](https://raw.githubusercontent.com/statelyai/xstate/d98d948a534b028f4af8b271eb431a8625ab5cb3/docs/guides/introduction-to-state-machines-and-statecharts/self-transition.svg)

## Planning statecharts

One of the benefits of statecharts is that, in the process of putting a statechart together, you explore all the possible states in your process. This exploration will help you avoid bugs and errors in your code as you’re more likely to cover all the eventualities.

And because statecharts are executable, they can behave as both the diagram and the code, making it less likely that you’ll introduce differences or bugs interpreting between the diagramming and coding environments.

### Planning a statechart for a login machine

To draw a statechart for a login machine, start by listing the basic _events_ in the process. Think about what your login process will _do_:

- log in
- log out

Then list the _states_ that exist as a result of those events:

- logged in
- logged out

Once there’s some events and states, there’s the beginnings of a statechart.

![Login statechart showing an initial logged out state transitioning through a log in event to a logged in state, then transitioning through a log out event back to the logged out state.](https://raw.githubusercontent.com/statelyai/xstate/d98d948a534b028f4af8b271eb431a8625ab5cb3/docs/guides/introduction-to-state-machines-and-statecharts/basic-login.svg)

Don’t forget the _initial state_. In this case, the **logged out** state is the initial state, as any new user would come to the process logged out.

## Delayed transitions

Some login and logout processes will log out an inactive user after a fixed length of time as a security measure.

The **active** and **idle** states only happen when the user is logged in, so these become child states inside the **logged in** compound state.



![](https://raw.githubusercontent.com/statelyai/xstate/d98d948a534b028f4af8b271eb431a8625ab5cb3/docs/guides/introduction-to-state-machines-and-statecharts/login-compound-state.svg)

The initial state inside the **logged in** compound state is **active**, as it happens as a direct result of the **log in** event, and logging in is a sign of user activity.

A _delayed transition_ is a type of transition which happens after being in a state for a specified length of time. The delayed transition is labelled with “after” and a fixed duration to indicate how much time should pass before transitioning to the next indicated state.

In the login statechart, a delayed transition of **60000** milliseconds, or 1 minute, follows the **active** state to determine whether the user is **idle**. If there is an **activity** event before the transition reaches one minute, the process returns to the **active** state.



![](https://raw.githubusercontent.com/statelyai/xstate/d98d948a534b028f4af8b271eb431a8625ab5cb3/docs/guides/introduction-to-state-machines-and-statecharts/delayed-transition.svg)

A delayed transition of **180000** milliseconds, or 3 minutes, follows the **idle** state to transition to the **auto logged out** state if the user remains idle.

## Actions

A statechart is used to set off _actions_ in the system outside of the statechart. Actions are also commonly known as _effects_ or _side-effects_. “Side effects” sounds like a negative or unimportant term, but setting off actions is the primary purpose in using statecharts.

Actions are events that have no impact or consequences for the rest of the sequence, the event is just triggered and the sequence moves on to the next step in the process. For example, the login statechart might execute actions that change the user interface.

An _action_ can be fired upon entering or exiting a state, or on a transition. An action on a state is included inside the state’s container with an “entry /” or “exit /” label depending on whether the action should be fired on entry or exit from the state.

In the login statechart, there’s an _entry_ action on the **idle** state to warn the user that they may be logged out.



![](https://raw.githubusercontent.com/statelyai/xstate/d98d948a534b028f4af8b271eb431a8625ab5cb3/docs/guides/introduction-to-state-machines-and-statecharts/entry-action.svg)

Introduction to state machines and statecharts


Managing state at different levels of complexity is hard. Different tools make different trade-offs between readability, complexity and speed of development. The worst part is that as apps get more complex, it’s easy to regret choices that were made early on.

This series of articles should help you make the right choice off the bat. The plan is to cover a bunch of state use cases, starting with the simple and graduating to more complexity as we go. We’ll see how easy they are to write, and also how they survive changing requirements.

Today, we’re starting with [modals](https://material-ui.com/components/modal/).

## useState

For modals, the key piece of state is whether or not the modal is open. `useState` lets us capture that single piece of state pretty succinctly.

```ts
const [isOpen, setIsOpen] = useState(false);

const open = () => {
  setIsOpen(true);
};

const close = () => {
  setIsOpen(false);
};

const toggle = () => {
  setIsOpen(!isOpen);
};
```

Highly readable, simple enough, fast to write, bug-proof. For a simple toggle like this, `useState` is great.

## useReducer

```ts
const reducer = (state = { isOpen: false }, action) => {
  switch (action.type) {
    case "OPEN":
      return {
        isOpen: true,
      };
    case "CLOSE":
      return {
        isOpen: false,
      };
    case "TOGGLE":
      return {
        isOpen: !state.isOpen,
      };
    default:
      return state;
  }
};

const [state, dispatch] = useReducer(reducer, { isOpen: false });

const open = () => {
  dispatch({ type: "OPEN" });
};

const close = () => {
  dispatch({ type: "CLOSE" });
};

const toggle = () => {
  dispatch({ type: "TOGGLE" });
};
```

`useReducer` gives us a reducer, a powerful centralized spot in our code where we can visualise the changes happening. However, it took us quite a few more lines of code to reach the same result as `useState`. For now, I’d say `useState` has the edge.

## useMachine

`useMachine` is a hook from XState, which allows us to use the power of state machines in our code. Let’s see how it looks.

```ts
const machine = Machine({
  id: "modalMachine",
  initial: "closed",
  states: {
    closed: {
      on: {
        OPEN: {
          target: "open",
        },
        TOGGLE: "open",
      },
    },
    open: {
      on: {
        TOGGLE: "closed",
        CLOSE: "closed",
      },
    },
  },
});

const [state, send] = useMachine(machine);

const open = () => {
  send({ type: "OPEN" });
};

const close = () => {
  send({ type: "CLOSE" });
};

const toggle = () => {
  send({ type: "TOGGLE" });
};
```

_You can see the state machine on the [XState visualiser here](https://xstate.js.org/viz/?gist=cf1578f5baa04cf9408ef6e48695f04c)._

It’s remarkably similar in structure to the reducer above. Similar amount of lines, nearly the same event handlers. The state machine takes the edge over the reducer because of being able to easily visualise its logic - that’s something the reducer can’t match.

However, the `useState` implementation still has the edge for me. The simplicity of execution, the elegance. It’s hard to see how it could be beaten...

## ALERT: REQUIREMENTS CHANGING

Oh no. Requirements have changed. Now, instead of immediately closing, the modal needs to animate out. This means we need to insert a third state, `closing`, which we automatically leave after 500ms. Let’s see how our implementations hold up.

### useState

**Refactor 1**: Our initial `isOpen` boolean won't handle all the states we need it to any more. Let’s change it to an enum: `closed`, `closing` and `open`.

**Refactor 2**: `isOpen` is no longer a descriptive variable name, so we need to rename it to `modalState` and `setModalState`.

**Refactor 3**: `useState` doesn’t handle async changes by itself, so we need to bring in `useEffect` to run a timeout when the state is in the `closing` state. We also need to clear the timeout if the state is no longer `closing`.

**Refactor 4**: We need to change the toggle event handler to add logic to ensure it only triggers on the `closed` and `open` states. Toggles work great for booleans, but become much harder to manage with enums.

```ts
// Refactor 1, 2
const [modalState, setModalState] = useState("closed");

// Refactor 3
useEffect(() => {
  if (modalState === "closing") {
    const timeout = setTimeout(() => {
      setModalState("closed");
    }, 500);
    return () => {
      clearTimeout(timeout);
    };
  }
}, [modalState]);

// Refactor 1, 2
const open = () => {
  setModalState("open");
};

// Refactor 1, 2
const close = () => {
  setModalState("closing");
};

// Refactor 1, 2, 4
const toggle = () => {
  if (modalState === "closed") {
    setModalState("open");
  } else if (modalState === "open") {
    setModalState("closing");
  }
};
```

Yuck. That was an enormous amount of refactoring to do just to add a simple, single requirement. On code that might be subject to changing requirements, think twice before using `useState`.

### useReducer

**Refactor 1**: Same as above - we turn the `isOpen` boolean to the same enum.

**Refactor 2**: Same as above, `isOpen` is now improperly named, so we need to change it to `status`. This is changed in fewer places than `useState`, but there are still some changes to make.

**Refactor 3**: The same as above, we use `useEffect` to manage the timeout. An additional wrinkle is that we need a new action type in the reducer, `REPORT_ANIMATION_FINISHED`, to cover this.

**Refactor 4**: The same as above, but instead of the logic being in the event handler, we can actually change the logic inside the reducer. This is a cleaner change, but is still similar in the amount of lines it produces.

```ts
// Refactor 1, 2
const reducer = (state = { status: "closed" }, action) => {
  switch (action.type) {
    // Refactor 2
    case "OPEN":
      return {
        status: "open",
      };
    // Refactor 2
    case "CLOSE":
      return {
        status: "closing",
      };
    // Refactor 3
    case "REPORT_ANIMATION_FINISHED":
      return {
        status: "closed",
      };
    // Refactor 4
    case "TOGGLE":
      switch (state.status) {
        case "closed":
          return {
            status: "open",
          };
        case "open":
          return {
            status: "closing",
          };
      }
      break;
    default:
      return state;
  }
};

// Refactor 1
const [state, dispatch] = useReducer(reducer, { status: "closed" });

// Refactor 3
useEffect(() => {
  if (state.status === "closing") {
    const timeout = setTimeout(() => {
      dispatch({ type: "REPORT_ANIMATION_FINISHED" });
    }, 500);
    return () => {
      clearTimeout(timeout);
    };
  }
}, [state.status]);

const open = () => {
  dispatch({ type: "OPEN" });
};

const close = () => {
  dispatch({ type: "CLOSE" });
};

const toggle = () => {
  dispatch({ type: "TOGGLE" });
};
```

This file required the same number of refactors as the `useState` implementation. One crucial advantage is that these refactors were mostly located together: most changes occurred inside the reducer, and the event handlers went largely untouched. For me, this gives `useReducer` the edge over `useState`.

### useMachine

**Refactor 1**: Add a new closing state, which after 500 milliseconds goes to the closed state.

**Refactor 2**: Changed the targets of the `TOGGLE` and `CLOSE` actions to point at `closing` instead of `closed`.

```ts
export const machine = Machine({
  id: "modalMachine",
  initial: "closed",
  states: {
    closed: {
      on: {
        OPEN: {
          target: "open",
        },
        TOGGLE: "open",
      },
    },
    // Refactor 1
    closing: {
      after: {
        500: "closed",
      },
    },
    open: {
      on: {
        // Refactor 2
        TOGGLE: "closing",
        CLOSE: "closing",
      },
    },
  },
});

const [state, send] = useMachine(machine);

const open = () => {
  send({ type: "OPEN" });
};

const close = () => {
  send({ type: "CLOSE" });
};

const toggle = () => {
  send({ type: "TOGGLE" });
};
```

> [See the changed machine here](https://xstate.js.org/viz/?gist=61bbac74d69894c9472571e44c98f765).

The difference here is stark. A minimal number of refactors, all within the state machine itself. The amount of lines has hardly changed. None of the event handlers changed. AND we have a working visualisation of the new implementation.

## Conclusion

Before the requirements changed, `useState` was the champion. It’s faster, easier to implement, and fairly clear. `useReducer` and `useMachine` were too verbose, but `useMachine` took the edge by being easier to visualise.

But after the requirements changed, `useState` hit the floor. It quickly became the _worst_ implementation. It was the hardest to refactor, and its refactors were in the most diverse places. `useReducer` was equally hard to refactor, with the same set of changes. `useMachine` emerged as the champion, with a minimal diff required to build in new, complex functionality.

So if you’re looking to build a modal fast, use `useState`. If you want to build it right, use `useMachine`.

I’m excited to work on this set of articles - I’m looking forward to tackling the toughest state models out there. What would you like to see covered in the next one? Some ideas:

- Data fetching
- Form state
- Multi-step sequences (checkout flows, signup flows)

Let me know in the comments below, and follow me for the next article!


Managing state at different levels of complexity is hard. This series of articles should help you make the right choices off the bat. Today we’re starting with modals.

useState vs useReducer vs XState - Part 1: Modals


_This article has become part of the official [XState docs](https://xstate.js.org/docs/recipes/react.html)!_

Many React applications follow the Flux architecture popularised by [Redux](https://redux.js.org/). This setup can be characterised by a few key ideas:

1. It uses a single object at the top of your app which stores all application state, often called the **store**.
2. It provides a single `dispatch` function which can be used to send messages up to the store. Redux calls these `action`s, but I'll be calling them `events` - as they're known in XState.
3. How the store responds to these messages from the app are expressed in pure functions - most often in **reducers**.

This article won't go into depth on whether the Flux architecture is a good idea. David Khourshid's article [Redux is half a pattern](https://dev.to/davidkpiano/redux-is-half-of-a-pattern-1-2-1hd7) goes into great detail here. For the purposes of this article, we're going to assume that you like having a global store, and you want to replicate it in XState.

There are many reasons for wanting to do so. XState is second-to-none when it comes to managing complex asynchronous behaviour and modelling difficult problems. Managing this in Redux apps usually involves middleware: either [redux-thunk](https://github.com/reduxjs/redux-thunk), [redux-loop](https://github.com/redux-loop/redux-loop) or [redux-saga](https://github.com/redux-saga/redux-saga). Choosing XState gives you a first-class way to manage complexity.

## A globally available store

To mimic Redux's globally-available store, we're going to use React context. React context can be a tricky tool to work with - if you pass in values which change too often, in can result in re-renders all the way down the tree. That means we need to pass in values which change as little as possible.

Luckily, XState gives us a first-class way to do that.

```ts
import React, { createContext } from "react";
import { useInterpret } from "@xstate/react";
import { authMachine } from "./authMachine";
import { ActorRefFrom } from "xstate";

interface GlobalStateContextType {
  authService: ActorRefFrom<typeof authMachine>;
}

export const GlobalStateContext = createContext(
  // Typed this way to avoid TS errors,
  // looks odd I know
  {} as GlobalStateContextType
);

export const GlobalStateProvider = (props) => {
  const authService = useInterpret(authMachine);

  return (
    <GlobalStateContext.Provider value={{ authService }}>
      {props.children}
    </GlobalStateContext.Provider>
  );
};
```

Using `useInterpret` returns a `service`, which is a static reference to the running machine which can be subscribed to. This value never changes, so we don't need to worry about wasted re-renders.

## Utilising context

Further down the tree, you can subscribe to the service like this:

```ts
import React, { useContext } from "react";
import { GlobalStateContext } from "./globalState";
import { useActor } from "@xstate/react";

export const SomeComponent = (props) => {
  const globalServices = useContext(GlobalStateContext);
  const [state] = useActor(globalServices.authService);

  return state.matches("loggedIn") ? "Logged In" : "Logged Out";
};
```

The `useActor` hook listens for whenever the service changes, and updates the `state` value.

## Improving Performance

There's an issue with the implementation above - this will update the component for any change to the service. Redux offers tools for deriving state using selectors - functions which restrict which parts of the state can result in components re-rendering.

Luckily, XState provides that too.

```ts
import React, { useContext } from "react";
import { GlobalStateContext } from "./globalState";
import { useSelector } from "@xstate/react";

const selector = (state) => {
  return state.matches("loggedIn");
};

export const SomeComponent = (props) => {
  const globalServices = useContext(GlobalStateContext);
  const isLoggedIn = useSelector(globalServices.authService, selector);

  return isLoggedIn ? "Logged In" : "Logged Out";
};
```

Now, this component will only re-render when `state.matches('loggedIn')` returns a different value. This is my recommended approach over `useActor` for when you want to optimise performance.
Dispatching events

For dispatching events to the global store, you can call a service's send function directly.

```ts
import React, { useContext } from "react";
import { GlobalStateContext } from "./globalState";

export const SomeComponent = (props) => {
  const globalServices = useContext(GlobalStateContext);

  return (
    <button onClick={() => globalServices.authService.send("LOG_OUT")}>
      Log Out
    </button>
  );
};
```

Note that you don't need to call useActor for this, it's available right on the context.

## Deviations from Flux

Keen-eyed readers may spot that this implementation is slightly different from Flux. For instance - instead of a single global store, one might have several running machines at once: `authService`, `dataCacheService`, and `globalTimeoutService`. Each of them have their own `send` attributes, too - so you're not calling a global dispatch.

These changes can be worked around. One could create a synthetic send inside the global store which called all the services' `send` function manually. But personally, I prefer knowing exactly which services my messages are being passed to, and it avoids having to keep events globally namespaced.

## Summary

XState can work beautifully as a global store for a React application. It keeps application logic co-located, treats side effects as first-class citizens, and offers good performance with `useSelector`. You should choose this approach if you're keen on the Flux architecture but feel your app's logic is getting out of hand.


How to manage global state with XState and React


XState offers several primitives for representing long-running application processes. These are usually expressed as [services](https://xstate.js.org/docs/guides/communication.html). I’ve written a bit about services [here](https://dev.to/mpocock1/xstate-should-this-be-an-action-or-a-service-2cp0) - but today I wanted to talk about my favourite way of expressing services: the Invoked Callback.

The [Invoked Callback](https://xstate.js.org/docs/guides/communication.html#invoking-callbacks) combines immense flexibility with good readability and a solid Typescript experience. They look like this:

```ts
createMachine({
  invoke: {
    src: (context, event) => (send, onReceive) => {
      // Run any code you like inside here

      return () => {
        // Any code inside here will be called when
        // you leave this state, or the machine is stopped
      };
    },
  },
});
```

Let’s break this down. You get access to `context` and `event`, just like promise-based services. But `send` is where things really get interesting. Let’s break down what makes `send` useful with an example.

## File Uploads

Imagine you need to build a file uploader, and you have a handy function called `startUpload` that uploads some data, and exposes an `onProgressUpdate` parameter to update the progress.

```ts
createMachine({
  context: {
    progress: 0,
  },
  initial: "idle",
  states: {
    idle: {
      on: {
        START: "pending",
      },
    },
    pending: {
      on: {
        PROGRESS_UPDATED: {
          assign: assign({
            progress: (context, event) => event.progress,
          }),
        },
        CANCEL: {
          target: "idle",
        },
      },
      invoke: {
        src: (context) => (send) => {
          const uploader = startUpload({
            onProgressUpdate: (progress) => {
              send({
                type: "PROGRESS_UPDATED",
                progress,
              });
            },
          });

          return () => {
            uploader.cancel();
          };
        },
      },
    },
  },
});
```

This machine starts in the `idle` state, but on the `START` event begins its invoked service, which uploads the file. It then listens for `PROGRESS_UPDATED` events, and updates the context based on its updates.

The `CANCEL` event will trigger the `uploader.cancel()` function, which gets called when the state is left. React users may recognise this syntax - it’s the same as the cleanup function in the [useEffect hook](https://reactjs.org/docs/hooks-reference.html#cleaning-up-an-effect).

Note how simple and idiomatic it is to cancel the uploader - just exit the state, and the service gets cleaned up.

## Event Listeners

The invoked callback’s cleanup function makes it very useful for event listeners, for instance `window.addEventListener()`. XState Catalogue’s [Tab Focus Machine](https://xstate-catalogue.com/machines/tab-focus) is a perfect example of this - copied here for ease:

```ts
createMachine(
  {
    initial: "userIsOnTab",
    states: {
      userIsOnTab: {
        invoke: {
          src: "checkForDocumentBlur",
        },
        on: {
          REPORT_TAB_BLUR: "userIsNotOnTab",
        },
      },
      userIsNotOnTab: {
        invoke: {
          src: "checkForDocumentFocus",
        },
        on: {
          REPORT_TAB_FOCUS: "userIsOnTab",
        },
      },
    },
  },
  {
    services: {
      checkForDocumentBlur: () => (send) => {
        const listener = () => {
          send("REPORT_TAB_BLUR");
        };

        window.addEventListener("blur", listener);

        return () => {
          window.removeEventListener("blur", listener);
        };
      },
      checkForDocumentFocus: () => (send) => {
        const listener = () => {
          send("REPORT_TAB_FOCUS");
        };

        window.addEventListener("focus", listener);

        return () => {
          window.removeEventListener("focus", listener);
        };
      },
    },
  }
);
```

When in the `userIsOnTab` state, we listen for the window’s `blur` event. When that happens, and `REPORT_TAB_BLUR` is fired, we clean up the event listener and head right on over to `userIsNotOnTab`, where we fire up the other service.

## Websockets

Invoked callbacks can also receive events via the `onReceive` function. This is perfect when you need to communicate to your service, such as sending events to websockets.

```ts
import { createMachine, forwardTo } from "xstate";

createMachine({
  on: {
    SEND: {
      actions: forwardTo("websocket"),
    },
  },
  invoke: {
    id: "websocket",
    src: () => (send, onReceive) => {
      const websocket = connectWebsocket();

      onReceive((event) => {
        if (event.type === "SEND") {
          websocket.send(event.message);
        }
      });

      return () => {
        websocket.disconnect();
      };
    },
  },
});
```

In order to receive events, services need an `id`. Not all events are forwarded to the invoked service, only those which we select via the `forwardTo` action.

Here, we can connect to the websocket, establish two-way communication, and clean it up all in a few lines of code.

## My Love Letter

Invoked callbacks are a concise, flexible method of invoking services in XState. There isn’t a case they can’t cover - and they’re one of my favourite parts of the XState API.


I’ve written a bit about services, but today I wanted to talk about my favourite way of expressing services: the Invoked Callback.

Why I love invoked callbacks


XState offers several ways of orchestrating side effects. Since it’s a statechart tool, [with significantly more power than a reducer](https://dev.to/mpocock1/usestate-vs-usereducer-vs-xstate-part-1-modals-569e), side effects are treated as a first-class concept.

‘Side effects’ as a concept spring from the idea of ‘pure’ functions. I.e. a function is at its best when it takes an input and returns an output. Pure functions don’t tend to involve:

- Waiting a set amount of time
- Making an API call to an external service
- Logging things to an external service

So we can think of all of the above as ‘side effects’ of our programme running. The name gives them a negative, medical, connotation - but really, they’re the meat of your app. Apps that don’t have side effects don’t talk to anything external, don’t worry about time, and don’t react to unexpected errors.

## Actions

> “Thank u, next.” - Ariana Grande

Side effects can be expressed in two ways in XState. First, as a fire-and-forget `action`. Let’s imagine that when the user opens this modal, we want to report to a logging service that this happened.

```ts
const modalMachine = createMachine(
  {
    initial: "closed",
    states: {
      closed: {
        on: {
          OPEN: "open",
        },
      },
      open: {
        entry: ["reportThatUserOpenedTheModal"],
        on: {
          CLOSE: "closed",
        },
      },
    },
  },
  {
    actions: {
      // Note that I'm declaring the action name above, but implementing
      // it here. This keeps the logic and implementation separate,
      // which I like
      reportThatUserOpenedTheModal: async () => {
        await fetch("/external-service/user-opened-modal");
      },
    },
  }
);
```

Actions are fire-and-forget, which means you can fire them off without worrying about consequences. If the action I declared above errors, my state machine won’t react - it’s already forgotten about it.

Actions represent a single point in time, like a dot on a graph. This means that you can place them very flexibly. Above, I’ve placed them on the `entry` attribute of the state, meaning that action will be fired when we enter the state. I could also place them on the transition:

```ts
const modalMachine = createMachine(
  {
    initial: "closed",
    states: {
      closed: {
        on: {
          OPEN: {
            actions: "reportThatUserOpenedTheModal",
            target: "open",
          },
        },
      },
      open: {
        on: {
          CLOSE: "closed",
        },
      },
    },
  },
  {
    actions: {
      reportThatUserOpenedTheModal: async () => {
        // implementation
      },
    },
  }
);
```

This means that whenever `OPEN` is called from the `closed` state, that action will be fired. In this modal, we could also fire the action whenever the user leaves the `closed` state, since we know they’ll be going to the `open` state.

```ts
const modalMachine = createMachine(
  {
    initial: "closed",
    states: {
      closed: {
        on: {
          OPEN: "open",
        },
        exit: ["reportThatUserOpenedTheModal"],
      },
      open: {
        on: {
          CLOSE: "closed",
        },
      },
    },
  },
  {
    actions: {
      reportThatUserOpenedTheModal: async () => {
        // implementation
      },
    },
  }
);
```

Actions are flexible precisely because we don’t care about their outcome. We can hang them on the hooks our state machine gives us: transitions between states, exiting states and entering states.

## Services

> “And I plan to be forgotten when I’m gone…” - The Tallest Man on Earth

But actions have a specific limitation - they are designed to be forgotten. Let’s imagine that you wanted to track whether the analytics call you made was successful, and only open the modal if it was. We’ll add an `opening` state which handles that check.

```ts
const modalMachine = createMachine({
  initial: "closed",
  states: {
    closed: {
      on: {
        OPEN: "opening",
      },
    },
    opening: {
      entry: [
        async () => {
          await fetch("/external-service/user-opened-modal");

          // OK, this was successful - how do I get to the open state?!
        },
      ],
    },
    open: {
      on: {
        CLOSE: "closed",
      },
    },
  },
});
```

This isn’t possible in an action. We can’t fire back an event to the machine, because it’s already forgotten about us.

When you care about the result of an action, put it in a service. This is how this would be expressed as a service:

```ts
const modalMachine = createMachine({
  initial: "closed",
  states: {
    closed: {
      on: {
        OPEN: "opening",
      },
    },
    opening: {
      invoke: {
        // This uses the invoked callback syntax - my favourite
        // syntax for expressing services
        src: () => async (send) => {
          await fetch("/external-service/user-opened-modal");

          send("OPENED_SUCCESSFULLY");
        },
        onError: {
          target: "closed",
        },
      },
      on: {
        OPENED_SUCCESSFULLY: {
          target: "open",
        },
      },
    },
    open: {
      on: {
        CLOSE: "closed",
      },
    },
  },
});
```

If actions are a dot on the graph, services represent a line - a continuous process which takes some amount of time. If the service errors, it’ll trigger an event called `error.platform.serviceName`, which you can listen for with the `onError` attribute, as above.

Crucially, they can also send events back to the machine, using the `send` function above. Notice that we’re both sending back the `OPENED_SUCCESSFULLY` event _and_ listening to it in the `on: {}` attribute of the `opening` state.

Services are less flexible than actions, because they demand more from you. You can’t hang them on every hook your machine offers. They must be contained within one state, and they’re cancelled when you leave that state. (Note: they can also be at the root of the machine definition, meaning they run for the lifetime of the machine.)

## Guidelines

Actions are the ‘thank u, next’ of the XState world. They represent points in time. Use them for fire-and-forget actions. Actions are great for:

- `console.log`
- Showing ephemeral error or success messages (toasts)
- Navigating between pages
- Firing off events to external services or parents of your machine

Services are like a ‘phase’ your machine goes through. They represent a length of time. Use them for processes where you care about the outcome, or you want the process to run for a long time. Services are great for:

- API calls
- Event listeners (`window.addEventListener`)


Whether to use an action or a service in XState.

Should this be an action, or a service?


State machines offer several API’s for expressing state. Like other tools, you can keep arbitrary values in a store (usually expressed as an object) called `context`.

This is handy for values which change over time and you need to keep updated, like the value of a form input:

```ts
import { createMachine, assign } from "xstate";

const machine = createMachine({
  context: {
    name: "",
  },
  on: {
    CHANGE_NAME: {
      actions: assign((context, event) => {
        return {
          name: event.value,
        };
      }),
    },
  },
});
```

Every time the `CHANGE_NAME` event is sent to the machine, we'll update the value in `context`. We can then use that value to display the value in our UI or send it to an API.

XState also gives you another way of expressing state - through finite states. Let's imagine a modal:

```ts
const machine = createMachine({
  initial: "closed",
  states: {
    closed: {
      on: {
        OPEN: "open",
      },
    },
    open: {
      on: {
        CLOSE: "close",
      },
    },
  },
});
```

Here, the modal's state is expressed through the `states: {}` attribute, which also defines which events can be received during each state. You can only `CLOSE` the modal when it's `open`, and vice versa.

## Which should I choose?

The choice between using `context` and `states` isn't always clear. For instance, the modal machine above could be expressed using `context`:

```ts
const machine = createMachine({
  context: {
    isOpen: false,
  },
  on: {
    OPEN: {
      actions: assign({ isOpen: true }),
    },
    CLOSE: {
      actions: assign({ isOpen: false }),
    },
  },
});
```

This gives you exactly the same functionality as the states-based one above - you can track when the modal is open and closed, and send the same events.

The reason this can be expressed using both `states` and `context` is because _all of the events do the same thing no matter what state you’re in_. There are no events you need to declare as impossible in certain states.

To show you what I mean, let’s imagine a form input inside a modal. We only want to allow changes to the form input while the modal is open.

```ts
const machine = createMachine({
  initial: "closed",
  context: {
    name: "",
  },
  states: {
    closed: {
      on: {
        OPEN: "open",
      },
    },
    open: {
      on: {
        CLOSE: "close",
        CHANGE_NAME: {
          actions: assign((context, event) => {
            return {
              name: event.value,
            };
          }),
        },
      },
    },
  },
});
```

When the modal is in the `closed` state, the `CHANGE_NAME` event will not change the value in `context`. State machines are great at this - only allowing the things you want to happen to happen. Some other examples might be:

- Not allowing users to submit a form while the previous API call is loading
- Only allowing users to log in if they’re not already logged in

## Putting things in context

You might be wondering - but, I _can_ express the above in `context`!

```ts
const machine = createMachine({
  context: {
    name: "",
    isOpen: false,
  },
  on: {
    OPEN: { actions: assign({ isOpen: true }) },
    CLOSE: { actions: assign({ isOpen: false }) },
    CHANGE_NAME: {
      actions: assign((context, event) => {
        // This acts as the guard to prevent editing
        // the name while it's open
        if (!context.isOpen) return {};
        return {
          name: event.value,
        };
      }),
    },
  },
});
```

I think this is incorrect for two reasons. First, as requirements grow, so will the complexity of your logic. Let’s imagine that the modal can now be either `closing` (i.e. animating out) or `closed`. We’ll soon see an explosion of booleans, as I discussed in [this article on useState/useReducer](https://dev.to/mpocock1/usestate-vs-usereducer-vs-xstate-part-1-modals-569e).

Second, XState is auto-documenting via the [XState visualiser](https://xstate.js.org/viz/). The more your logic is expressed in `states`, the easier it’s going to be to visualise. The machine above is basically a single state with its logic expressed in ways that XState can’t visualise.

## Rules to live by

You should be keeping most of your state in context. That includes form values, API data - anything which cannot be expressed finitely.

But state machines are powerful _because_ of their states. Use states when you want to express your logic visually, or gate events to certain states.


How to decide when to use state or context.

Should this be a state, or in context?


XState offers two options for declaring machine definitions:

```ts
import { Machine } from "xstate";

const machine = Machine({ ...config });
```

…or…

```ts
import { createMachine } from "xstate";

const machine = createMachine({ ...config });
```

This can be confusing for beginners. Why are there two very similar-looking methods? What’s the difference?

## The Difference

In Javascript, there is no difference between the two. You can use them completely interchangeably.

In Typescript, there is only a small difference between them - it’s to do with the ordering of the generics you can pass to the machine. `Machine` allows you to pass a generic called ['Typestates'](https://xstate.js.org/docs/guides/typescript.html#typestates) in the middle of the `Context` and `Event` generics.

```ts
import { Machine } from "xstate";

interface Context {}

type Event = { type: "EVENT_NAME" };

type States = {};

const machine = Machine<Context, States, Event>({ ...config });
```

Whereas `createMachine` asks you to insert it at the end:

```ts
import { createMachine } from "xstate";

interface Context {}

type Event = { type: "EVENT_NAME" };

type States = {};

const machine = createMachine<Context, Event, States>({ ...config });
```

Whichever you choose, there is _no functional difference in the created machine_. The two functions reference the same code, and create the machine in the same way.

## What should I choose?

Going forward, you should use `createMachine`. That’s the syntax that will be preferred when v5 releases. But if you're happy with Machine, you can keep using it.


XState offers two options for declaring machine definitions. This can be confusing for beginners. Why are there two very similar-looking methods? What’s the difference?

What’s the difference between Machine and createMachine?


The finite state machine is one of the oldest models of computation in computer science. It’s older than the web, older than any programming language you can think of, and probably older than you. Just ask [Mealy (1955)](https://en.wikipedia.org/wiki/Mealy_machine) or [Moore (1956)](https://en.wikipedia.org/wiki/Moore_machine). Finite state machines (FSMs) can be implemented in any modern language using control-flow statements, yet there’s most likely a state machine library (if not many) in all of those languages.

So do you need a library to create and interpret state machines in your programs?

**No.** But there are more things to consider.

## You probably need state machines

If you’re unfamiliar with [finite state machines (FSMs)](https://en.wikipedia.org/wiki/Finite-state_machine), they are a visual and mathematical way of modeling stateful logic using 3 main building blocks:

- **Finite states**, which represent different _behaviors_
- **Events**, which represent something that happened that can change state
- **Transitions**, which represent how the state can change and what actions are executed when an event is received

![States, events, and transitions](https://res.cloudinary.com/practicaldev/image/fetch/s--NRBTk8Po--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to-uploads.s3.amazonaws.com/i/7ri5sbbrufj26cq3u026.png)

Anything that can be described as changes in state over time due to events, from component-specific logic to application flows and even the orchestration of multiple services can be described with state machines, to some extent.

A state machine might be a different, unfamiliar way of thinking about your application logic, but they’re extremely useful. Instead of approaching logic from a "bottom-up" perspective (imperatively doing things based on events), they take a "top-down" approach and primarily consider _behaviors_, which describe how the logic will react to events in a given finite state (such as `loading`, `editing`, `disabled`, etc.).

Because of their explicit, declarative nature, state machines force you to think about the entire flow of your logic (including all the edge-cases), and make it virtually impossible to end up in an ”impossible state”, as long as your model doesn’t allow it. Only defined transitions can happen; and if an unexpected transition happens, it means there is an implicit state machine where that transition _does_ exist. The goal of state machines is to eliminate the implicit transitions so that we can know exactly what can happen in any state for any potential event.

State machines are **not a solution for everything** - just like anything else, they make sense for some use-cases (workflows, processes, modes, statuses, etc.) but not all use-cases. You shouldn’t use state machines everywhere, or even implement them explicitly all of the time (that’s what abstractions are for). They make a good refactor target, and they’re great for visually modeling your logic with pencil and paper, even if you ultimately decide not to use them in your code. But when working with logic that deals with explicit states, events, and transitions (which, surprise, tends to be the majority of app logic), state machines are a brilliant, natural solution.

There are so many other benefits to thinking in terms of states, events, and transitions, but that’s not the point of this post (but it is the point of [another post I wrote](https://dev.to/davidkpiano/no-disabling-a-button-is-not-app-logic-598i)). Let’s say you’re already convinced in using state machines in parts of your app. Should you reach for a library?

## You don’t need a library for state machines

Since state machines are not a new concept and can be implemented in any modern language using built-in language features, it follows that state machine libraries are not necessary. Again, all you need are the 3 building blocks:

- **Finite states**
- **Events**
- **Transitions**

The transitions are what tie everything together. Transitions are represented by a [state-transition function](https://en.wikipedia.org/wiki/Finite-state_machine#Mathematical_model) that looks like this, mathematically:

> 𝛅 : 𝑆 𝗑 𝛴 → 𝑆

…which might not make sense (even if you do speak Greek). This might be more understandable:

> transition : (state, event) => nextState

In JavaScript, we can represent this as a _reducer_, which is a function that reduces values (events) to a single accumulated value (state):

```js
function transition(state, event) {
  // state machine goes here, which
  // determines the next state based on the
  // current state + received event
  // ...

  return nextState;
}
```

Now, let’s draw the rest of the owl implement the rest of the state machine!

### Using `switch` statements

Typically, when we’re determining _behavior_ ("what happens next"), we tend to decide what should happen next based on the _event_. The finite state is an after-thought, if it’s even a consideration at all. This leads to fragile logic, with `if`\-statements strewn all over the place:

```js
    // ❌ Event-first approach
    switch (event.type) {
      case 'DATA_RECEIVED':
        // defensive programming
        if (state.isLoading) {
          // do something
        } else {
          // ...
        }
      }
      // ...
    }
```

In contrast, state machines group behavior by **finite state** and narrow down what happens next based on the event received:

```js
// ✅ Finite-state-first approach
switch (state.status) {
  case "loading":
    // narrow based on event
    switch (event.type) {
      case "DATA_RECEIVED":
      // do something, and possibly
      // change the finite state
      // ...
    }
  // ...
}
```

As the author of the code, the event-first (bottom-up) approach might seem fine to you; after all, if it works, it works. One of the main advantages of taking a ”finite-state-first” (top-down) approach and using state machines is that the logic is not only more clear (since it’s grouped by finite state), it’s more robust: you can ensure that an event won’t be improperly handled in a state that it shouldn’t be handled in. In other words, you prevent _impossible states_ and _impossible transitions_ without having to litter your code with `if`\-statements and excessive defensive programming.

I also like to think of state machines as a formal way of communicating logic. If you were describing the above logic, here’s how it would sound with an event-first approach:

> When data is received, do something, but only if the "loading" flag is true.

And with a finite-state-first approach:

> In the ”loading” state, when data is received, do something.

Which one sounds more natural and easy to understand? To me, there is less cognitive load with the 2nd statement. Reactions to events are grouped by _behavior_ (finite state) rather than being ungrouped.

### Using `switch` statements with functions

Since finite states can be considered a way to group behavior, another way you can organize your `switch` statements is by “grouping” each finite state’s behavior into a function:

```js
    // 'loading' behavior
    function loadingState(state, event) {
      // switch only on the event
      switch (event.type) {
        case 'DATA_RECEIVED':
          return {
            ...state,
            status: 'success'
          }
        }
        // ...
      }
    }

    function dataMachine(state, event) {
      switch (state.status) {
        case 'loading':
          // handle the event with 'loading' behavior
          return loadingState(state, event);
        }
        // ...
      }
    }
```

This approach is outlined in the [Redux style guide recommendation: Treat Reducers as State Machines](https://redux.js.org/style-guide/style-guide/#treat-reducers-as-state-machines). It’s a very organized approach, and each “behavior function” can be individually tested, since they are isolated, pure reducers.

### Using objects

Using nested `switch` statements may feel verbose, and while using functions to organize these `switch` statements may look cleaner, it’s more tedious. After all, a state transition can be considered a configuration of (at least) 2 things based on the event received:

- The next **finite state**, if it changes
- Any **action(s)** executed, if any

A simple, built-in way to represent such a configuration is an object. We can create an object structure where each ”state node” represents a finite state with transitions for each event accepted by the state:

```js
const machine = {
  initial: "loading",
  states: {
    // A finite "state node"
    loading: {
      on: {
        // event types
        DATA_RECEIVED: {
          target: "success",
          // actions: [...]
        },
      },
    },
    // ...
  },
};
// ...
```

This is much more succinct than the nested `switch` statements! From here, determining the next state based on the current finite state and received event is two key lookups (the finite state and the event type):

```js
// ...
function transition(state, event) {
  const nextStateNode = // lookup next finite state based on event type
    // lookup configuration for current finite state
    machine.states[state.status].on?.[event.type] ?? { target: state.status }; // if not handled, stay on current state

  return {
    ...state,
    status: nextStateNode.target,
  };
}

transition({ status: "loading" }, { type: "DATA_RECEIVED" });
// => { status: 'success', ... }
```

You might be wondering why I didn’t use an even simpler object here, which you definitely can do:

```js
const transitions = {
  loading: {
    DATA_RECEIVED: "success",
  },
  success: {
    /* ... */
  },
};

function transition(state, event) {
  const nextStateTarget = transitions[state.status][event.type] ?? state.status;

  return {
    ...state,
    status: nextStateTarget,
  };
}
```

In fact, I would encourage the above implementation as sort of a “transition table lookup”; it works, and it’s simple enough. However, state machines deal with more than just the next finite state; if we want to encode **actions** (state machine terminology for effects), we need a place to put them, so a little bit more structure is necessary.

For instance, if our `DATA_RECEIVED` event returns data that we want to save in our overall state, it might be convenient to place that “assign to state” action directly in the machine:

```js
const machine = {
  initial: "loading",
  states: {
    loading: {
      on: {
        // event types
        DATA_RECEIVED: {
          target: "success",
          // represents what "effects" should happen
          // as a result of taking this transition
          actions: [{ type: "saveData" }],
        },
      },
    },
    // ...
  },
};

function transition(state, event) {
  const nextStateNode = machine.states[state.status].on?.[event.type] ?? {
    target: state.status,
  };

  const nextState = {
    ...state,
    status: nextStateNode.target,
  };

  // go through the actions to determine
  // what should be done
  nextStateNode.actions?.forEach((action) => {
    if (action.type === "saveData") {
      nextState.data = event.data;
    }
  });

  return nextState;
}
```

The implementation above is very small, accomplishes everything we want from a state machine (for this use-case, at least), and as a bonus, you can copy-paste the `machine` object code directly into the [XState Visualizer](https://xstate.js.org/viz), even though it's not using XState, or any libraries, at all! (Tip: wrap the object in `Machine({ ... })` to get it working).

Kent C. Dodds made a similar implementation is his post [Implementing a Simple State Machine Library in JavaScript](https://kentcdodds.com/blog/implementing-a-simple-state-machine-library-in-javascript). It also takes advantage of using objects for describing the state machine structure.

## State machines aren't enough

So if we can get our basic state management needs met with a small, declarative, library-free state machine implementation (either using `switch` statements or objects), why do we need libraries such as [XState](https://github.com/davidkpiano/xstate)?

This might be a bit of a shock coming from me, but I’ll say it: _state machines are not sufficient_ for managing and orchestrating state at scale. State machines suffer from a fundamental problem called [state explosion](https://statecharts.github.io/state-machine-state-explosion.html): when the number of states in a state machine grow, the transitions between states also tend to grow, _exponentially_.

Thankfully, an extension to the traditional formalism of state machines, known as **statecharts**, was invented by Prof. David Harel and published in his paper [Statecharts: A Visual Formalism for Complex Systems](https://www.sciencedirect.com/science/article/pii/0167642387900359/pdf). The paper is full of diagrams and is quite readable; I strongly encourage you to read it.

You can think of statecharts as essentially being state machines (statecharts can be decomposed into FSMs) with some essential features for better state organization and real-world use-cases:

- **Hierarchy** (nested states)
- **Orthogonality** (parallel states)
- **History** (remembered states)
- **State actions** (entry, exit)
- **Guarded transitions**
- **Extended state** (contextual data)

Notably, the first two features (hierarchy and orthogonality) mitigate the state explosion problem by allowing state nodes to be grouped in a way that reduces the number of transitions necessary to fully express all possible transitions.

For example, if you were creating a state machine to represent editing and asynchronously saving some data, and you wanted to have shared behavior between some ”idle” (before saving) and “error” (failure after saving) state (e.g., `SUBMIT` to try/retry), then instead of having a flat state machine:

```js
    {
      idleNormal: {
        on: {
          SAVE: {
            target: 'saving',
            actions: [{ type: 'saveAsync' }]
          }
        }
      },
      saving: {/* ... */},
      idleError: {
        on: {
          SAVE: {
            target: 'saving',
            actions: [{ type: 'saveAsync' }]
          }
        }
      },
      // ...
    }

```

You can represent the shared behavior under the same parent state:

```js
    {
      idle: {
        // if child states don't handle these events,
        // handle it here, in the parent state
        on: {
          SAVE: {
            target: 'saving',
            actions: [{ type: 'saveAsync' }]
          }
        },
        initial: 'normal',
        states: {
          normal: {/* ... */},
          error: {/* ... */}
        }
      },
      saving: {/* ... */},
      // ...
    }
```

Overall, the features of statecharts are very useful in many different situations:

- **Nested states** are useful for grouping and refining behavior. Different ”finite states” can all share behavior, while all having their own specific behavior.
- **Parallel states** are useful for representing behaviors that can occur simultaneously, without directly affecting each other.
- **History states** are useful for recalling which nested state the machine was previously in without having to specify all the possible ”remembering” transitions.
- **State actions** are useful for specifying actions that should always be executed on any transition that enters/exits a state without having to specify those actions in all incoming/outgoing transitions.
- **Guarded transitions** are very important for conditionally taking transitions based on more than just the state and event type. They can take other data (extended state) and/or event data into consideration, as well.
- **Extended state** is absolutely necessary. Not all state is finite; ”infinite” state also needs to be quantified. Statecharts allow you to distinguish between finite and extended state.

There's even more features of classic statecharts, such as ”activities” (actions that occur _throughout_ a state), delays, eventless transitions, wildcard transitions, and more. And the more you work with statecharts, the more you realize just how essential most of these features actually are.

Sounds like it would be fun to implement these features on top of our state machines, right?

## Implementing statecharts

I hope you have a _lot_ of free time.

Since statecharts are more powerful than state machines, they’re also harder to implement. If you’re really curious and/or eager to implement them yourself, I strongly recommend following the [W3 SCXML (Statechart XML) spec](https://www.w3.org/TR/scxml). They even include [an algorithm in pseudocode](https://www.w3.org/TR/scxml/#AlgorithmforSCXMLInterpretation) for proper SCXML interpretation.

Even implementing something as seemingly straightforward as nested states is a daunting task. There are many rules about selecting transitions, resolving conflicting transitions, traversing the state node tree to determine which nodes are being exited/entered, selecting transitions in compound states if leaf nodes don't handle the event, determining action order, etc. etc.

It’s not easy, and just like you would use a date library to deal with timezones, you definitely want to use a statechart library to deal with all the excellent features that statecharts support.

## So do you need a library for statecharts?

Yes.

## Closing thoughts

If you’re satisfied manipulating state at any time and sprinkling `if`\-statements to patch up edge-cases, you probably don’t need explicit state machines.

If you want to use simple state machines to help organize app behavior and logic, you don’t need a library.

If you have complex logic and want to take advantage of more powerful state machine features to better manage this logic, you need statecharts.

And you _definitely_ need a library for statecharts. 😉


Do you need a library to create and interpret state machines in your programs? No. But there are more things to consider.

You don’t need a library for state machines


XState can feel overwhelming. Once you’ve gone through [Kyle](https://egghead.io/courses/introduction-to-state-machines-using-xstate) or [David’s](https://frontendmasters.com/courses/xstate/) courses and read through the [docs](https://xstate.js.org/docs), you’ll get a thorough understanding of the API. You’ll see that XState is the most powerful tool available for managing complex state.

The challenge comes when integrating XState with React. Where should state machines live in my React tree? How should I manage parent and child machines?

<Tweet id="1345085887026106368" />

## Just Use Props

I’d like to propose an architecture for XState and React which prioritises simplicity, readability and type-safety. It’s incrementally adoptable, and gives you a base for exploring more complex solutions. We’ve used it at [Yozobi](https://www.yozobi.com/) in production, and we’re planning to use it for every project moving forward.

It’s called **just use props**. It’s got a few simple rules:

1. Create machines. Not too many. Mostly useMachine
2. Let React handle the tree
3. Keep state as local as possible

### Create machines. Not too many. Mostly useMachine

The simplest way to integrate a state machine in your app is with `useMachine`.

```ts
import { createMachine, interpret } from "xstate";
import { useMachine } from "@xstate/react";

const machine = createMachine({
  initial: "open",
  states: {
    open: {},
    closed: {},
  },
});

const Component = () => {
  const [state, send] = useMachine(machine);

  return state.matches("open") ? "Open" : "Closed";
};
```

Note that this puts React in charge of the machine. The machine is tied to the component, and it obeys all the normal React rules of the [data flowing down](https://reactjs.org/docs/state-and-lifecycle.html#the-data-flows-down). In other words, you can think of it just like `useState` or `useReducer`, but a [vastly improved version](https://dev.to/mpocock1/usestate-vs-usereducer-vs-xstate-part-1-modals-569e).

### Let React handle the tree

Let’s say you have a parent component and a child component. The parent has some state which it needs to pass to the child. There are several ways to do this.

#### Passing services through props

The first is to pass a running service to the child which the child can subscribe to:

```ts
import { useMachine, useService } from "@xstate/react";
import { createMachine, Interpreter } from "xstate";

/**
 * Types for the machine declaration
 */
type MachineContext = {};
type MachineEvent = { type: "TOGGLE" };

const machine = createMachine<MachineContext, MachineEvent>({});

const ParentComponent = () => {
  /**
   * We instantiate the service here...
   */
  const [state, send, service] = useMachine(machine);

  return <ChildComponent service={service} />;
};

interface ChildComponentProps {
  service: Interpreter<MachineContext, any, MachineEvent>;
}

const ChildComponent = (props: ChildComponentProps) => {
  /**
   * ...and receive it here
   */
  const [state, send] = useService(props.service);

  return (
    <button onClick={() => send("TOGGLE")}>
      {state.matches("open") ? "Open" : "Closed"}
    </button>
  );
};
```

I don’t like this pattern. For someone not used to XState, it’s unclear what a ‘service’ is. We don’t get clarity from reading the types, which is a particularly ugly `Interpreter` with multiple generics.

The machine appears to bleed across multiple components. Its service seems to have a life of its own, outside of React's tree. To a newbie, this feels like misdirection.

#### Just pass props

This can be expressed much more cleanly using props:

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

/**
 * Types for the machine declaration
 */
type MachineContext = {};
type MachineEvent = { type: "TOGGLE" };

const machine = createMachine<MachineContext, MachineEvent>({});

const ParentComponent = () => {
  const [state, send] = useMachine(machine);

  return (
    <ChildComponent
      isOpen={state.matches("open")}
      toggle={() => send("TOGGLE")}
    />
  );
};

/**
 * Note that the props declarations are
 * much more specific
 */
interface ChildComponentProps {
  isOpen: boolean;
  toggle: () => void;
}

const ChildComponent = (props: ChildComponentProps) => {
  return (
    <button onClick={() => props.toggle()}>
      {props.isOpen ? "Open" : "Closed"}
    </button>
  );
};
```

Much better. We get several improvements in clarity in the `ChildComponent` - the types are much easier to read. We get to ditch the use of `Interpreter` and `useService` entirely.

The best improvement, though, is in the `ParentComponent`. In the previous example, the machine crossed multiple components by passing its service around. In this example, it’s scoped to the component, and props are derived from its state. This is far easier to grok for someone unused to XState.

### Keep state as local as possible

Unlike tools which require a global store, XState has no opinion on where you keep your state. If you have a piece of state which belongs near the root of your app, you can use React Context to make it globally available:

```ts
import React, { createContext } from "react";
import { useMachine } from "@xstate/react";
import { createMachine } from "xstate";

const globalMachine = createMachine({});

interface GlobalContextType {
  isOpen: boolean;
  toggle: () => void;
}

export const GlobalContext = createContext<GlobalContextType>();

const Provider: React.FC = ({ children }) => {
  const [state, send] = useMachine(globalMachine);

  return (
    <GlobalContext.Provider
      value={{ isOpen: state.matches("open"), toggle: () => send("TOGGLE") }}
    >
      {children}
    </GlobalContext.Provider>
  );
};
```

_Just as above, we’re not passing a service, but props, into context._

If you have a piece of state which needs to belong lower in your tree, then obey the usual rules by [lifting state up](https://reactjs.org/docs/lifting-state-up.html) to where it’s needed.

If that feels familiar, you’re right. You’re making the same decisions you’re used to: where to store state and how to pass it around.

## Examples and challenges

### Syncing parents and children

Sometimes, you need to use a parent machine _and_ a child machine. Let’s say that you need the child to pay attention to when a prop changes from the parent - for instance to sync some data. Here’s how you can do it:

```ts
const machine = createMachine({
  initial: "open",
  context: {
    numberToStore: 0,
  },
  on: {
    /**
     * When REPORT_NEW_NUMBER occurs, sync
     * the new number to context
     */
    REPORT_NEW_NUMBER: {
      actions: [
        assign((context, event) => {
          return {
            numberToStore: event.newNumber,
          };
        }),
      ],
    },
  },
});

interface ChildComponentProps {
  someNumber: number;
}

const ChildComponent = (props: ChildComponentProps) => {
  const [state, send] = useMachine(machine);

  useEffect(() => {
    send({
      type: "REPORT_NEW_NUMBER",
      newNumber: props.someNumber,
    });
  }, [props.someNumber]);
};
```

This can also be used to sync data from other sources, such as query hooks:

```ts
const ChildComponent = () => {
  const [result] = useSomeDataHook(() => fetchNumber());

  const [state, send] = useMachine(machine);

  useEffect(() => {
    send({
      type: "REPORT_NEW_NUMBER",
      newNumber: result.data.someNumber,
    });
  }, [result.data.someNumber]);
};
```

## Summary

In the “just use props” approach, XState lets React take charge. We stick to idiomatic React by passing props, not services. We keep machines scoped to components. And we put state at the level it’s needed, just like you’re used to.

This article isn’t finished. I’m sure there will be many more questions about integrating XState with React. My plan is to come back to this article again with more examples and clarifications. Thanks for your time, and I’m looking forward to seeing what you build with XState.


XState is the most powerful tool available for managing complex state. The challenge comes when integrating XState with React…

“Just use props”: An opinionated guide to React and XState


My code contains [Horcruxes](https://harrypotter.fandom.com/wiki/Horcrux). I’m not proud to admit it, since to make a Horcrux you need to commit a murder. The murders seemed intuitive at the time, and were usually for expedience. But nonetheless, I am a murderer.

Let’s talk about how I got here.

## The Soul of your app’s logic

For an app to remain maintainable, its soul must remain intact. For many apps, logic is usually expressed in changes to state and behaviour.

For instance, some logic for a modal might be expressed like this:

```ts
const modalReducer = (state = { isOpen: false }, action) => {
  switch (action.type) {
    case "CLOSE":
      return {
        isOpen: false,
      };
    case "OPEN":
      return {
        isOpen: true,
      };
    default:
      return state;
  }
};
```

This is the reducer pattern, popularised by libraries like [Redux](https://redux.js.org/introduction/getting-started). In [React](https://reactjs.org/), we'd use this reducer in a `useReducer` hook:

```ts
const [state, dispatch] = useReducer(modalReducer);

<button onClick={() => dispatch({ type: "OPEN" })}>Open Modal</button>;
```

If you want to know what happens when you dispatch the `OPEN` action, you only need look in one place: the `modalReducer`. This part of your app is easy to keep bug-free, because all the logic for how it works is contained in one place.

But let’s say that requirements change. Now, before you open the modal you’ll need to fetch something from the API to check if you can open it. This seems intuitive enough:

```ts
    const [state, dispatch] = useReducer(modalReducer);

    <button onClick={async () => {
      const canOpenTheModal = await checkIfUserCanOpenIt();
      if (canOpenTheModal) {
        dispatch({ type: 'OPEN' });
      }
    }>
      Open Modal
    </button>
```

The `onClick` handler is now making the API check to see if it should open the modal. If there’s a bug with the way the modal opens, there are now two places you need to check, the reducer and the event handler.

The soul of your business logic has been split. Just like that, you made a Horcrux.

## Going beyond usual evil

The first Horcrux is never really the issue. You can survive one or two splits in your business logic. The trouble comes when you reach six or seven, split out over several 800-line files. I have wept over classes with dozens of methods, sequences with dozens of asynchronous steps.

Logic split into more than one place cannot be visualised. If it can’t be visualised, it can’t be modified, deleted or extended safely.

Let me make this plain: **Any code that cannot be concretely visualised will, at some point, result in a bug.**

There are several ways of mitigating horcruxes. You can push to make your code more readable, writing clean event handlers which don’t contain any logic. You can try to colocate as much as your logic as possible, for instance using [ducks](https://github.com/erikras/ducks-modular-redux) patterns.

But now we know that visualisation can prevent bugs, why not go further?

## Statecharts

I recently embarked on the most complex task I’d ever attempted as a developer - building a video chat app with multiple third-party integrations. Most of the business logic would take place on a single page - the chat portal. I needed to handle multiple user types, chat, notifications, input changes... And many more things.

I’d been using [XState](https://github.com/davidkpiano/xstate), and read that it could be used for visualising complex behaviours, such as Ryan Florence’s checkout:

<Tweet id="1084248892072329216" />

It produces clickable visualisations which you can share and walk through. For instance, the modal reducer above could be expressed in [this statechart](https://xstate.js.org/viz/?gist=56c56d2be397c4d5bea934c6d89e788d).

![A statechart describing a modal which opens and closes](https://res.cloudinary.com/practicaldev/image/fetch/s--XmLhsdr5--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to-uploads.s3.amazonaws.com/i/2lb0ctiu7s207t9w44mg.png)

I knew that if I wasn’t careful, I’d end up with 25-30 horcruxes under my belt, logic carried in dozens of event handlers. So I wrote the machine in XState. I even wrote a VSCode extension so I could have the visualiser inline as I went along. Here’s what I ended up with:

![An XState diagram of my video chat app](https://res.cloudinary.com/practicaldev/image/fetch/s--oY3xYHhl--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to-uploads.s3.amazonaws.com/i/33vxe2bcsxn8uvfzlgva.png)

Every part of this crazy complex app can now be visualised. I can see which conditions lead to which states. I can which actions are called on which events.

At an early stage of the process, I was even able to ask the client about complex interactions in the logic, just by walking them through the statechart. Weeks later, when it needed extending, I was able to insert a new piece of state without breaking anything else.

Any time someone needs to see how the viewing page works, they can fire up the visualiser. Their usual first reaction is one of terror. State machines don't create complexity, they reveal it. But by clicking through the machine, they can concretely see how the app works, and feel comfortable making changes.

## Make a bet on XState

---

If you’re having trouble deciphering the logic of a legacy app, try visualising it in XState. Try working through a problem with a fellow dev. At [Yozobi](http://yozobi.com/), we’re making a bet that state machines are going to change web development. If you want to learn more about them, follow me and we can try to heal our Horcruxes together.


There are several ways of mitigating horcruxes. But visualisations can prevent bugs, so why not go further?

State machines: How to stop making Horcruxes in your code


**TL;DR**: Bad booleans represent state. Good booleans are derived from state.

When you’re managing state in your app, it’s easy to fall prey to bad booleans. Bad booleans look like this:

```js
let isLoading = true;
let isComplete = false;
let hasErrored = false;
```

On the surface, this looks like good code. It appears as though you’ve represented three separate states with proper boolean names. In the ‘model’ you’ve pictured for your state, only one of these states can be true at any one time.

In a fetch request, you might model the state like this:

```js
const makeFetch = async () => {
  isLoading = true;
  try {
    await fetch("/users");

    isComplete = true;
  } catch (e) {
    hasErrored = true;
  }
  isLoading = false;
};
```

Again, this looks nice. We’re orchestrating our booleans as we move through the async request.

But there’s a bug here. What happens if we make the fetch, it succeeds, and we make the fetch again? We’ll end up with:

```js
let isLoading = true;
let isComplete = true;
let hasErrored = false;
```

## Implicit states

You probably hadn’t considered this when you made your initial model. You may have frontend components which are checking for `isComplete === ` true or `isLoading === true`. You might end up with a loading spinner and the previous data showing at the same time.

How is this possible? Well, you’ve created some implicit states. Let’s imagine you considered 3 states as ones you actually wanted to handle:

1. `loading`: Loading the data
2. `complete`: Showing the data
3. `errored`: Erroring if the data doesn't turn up

Well, you’ve actually allowed 8 states! That’s 2 for the first boolean, times 2 for the second, times 2 for the third.

This is what's known as boolean explosion - I learned about this from [Kyle Shevlin's egghead course](https://egghead.io/lessons/javascript-eliminate-boolean-explosion-by-enumerating-states).

## Making states explicit

How do you get around this? Instead of a system with 8 possible values, we need a system with three possible values. We can do this in Typescript with an enum.

```ts
type Status = "loading" | "complete" | "errored";

let status: Status = "loading";
```

We’d implement this in a fetch like this:

```ts
const makeFetch = async () => {
  status = "loading";
  try {
    await fetch("/users");

    status = "complete";
  } catch (e) {
    status = "errored";
  }
};
```

It’s now impossible to be in the 'loading' and 'complete' state at once - we’ve fixed our bug. We’ve turned our bad booleans into a good enum.

## Making good booleans

But not all booleans are bad. Many popular libraries, such as _react-query_, _apollo_ and _urql_ use booleans in their state. An example implementation:

```js
const [result] = useQuery();

if (result.isLoading) {
  return <div>Loading...</div>;
}
```

The reason these are good booleans is that their underlying mechanism is based on an enum. Bad booleans represent state. Good booleans are derived from state:

```js
let status: Status = "loading";

// Derived from the status above
let isLoading = status === "loading";
```

You can safely use this `isLoading` to display your loading spinner, happy in the knowledge that you've removed all impossible states.

## Addendum: Enums in Javascript

We can represent a state enum in Javascript as well. While the above code will work without typings, you can represent enums as an object type.

```ts
const statusEnum = {
  loading: "loading",
  complete: "complete",
  errored: "errored",
};

let status = statusEnum.loading;

const makeFetch = async () => {
  status = statusEnum.loading;
  try {
    await fetch("/users");

    status = statusEnum.complete;
  } catch (e) {
    status = statusEnum.errored;
  }
};
```


TL;DR: Bad booleans represent state. Good booleans are derived from state

State Management: How to tell a bad boolean from a good boolean


I wrote a form library once.

_Once._

It was called [React Redux Form](https://github.com/davidkpiano/react-redux-form), and using Redux for forms was a good idea, at the time (don't use it). In fact, my library was written as a response to [Redux Form](https://github.com/redux-form/redux-form), and both libraries soon discovered that the idea of using a _single global store_ to store all of your application state is a really, really bad idea.

When all of your forms live in one single store, state is easy to manage at first. And then, every single keypress starts to lag. It's a terrible user experience.

So what do you do?

- Blur inputs
- Add debounced updates
- Memoize _everything_
- Optimize selectors everywhere
- Make controlled components uncontrolled
- Use `React.memo()` on components
- Use `PureComponent` for good measure
- Use Suspense (??)
- etc. etc.

In short, you go into panic mode and try to contain the spread of the global updates affecting every single connected component, even if those components don't need to rerender.

Some of you have gotten really good at solving this, and have become expert "selector, caching, and memoization" developers. That's fantastic.

But let's examine if those tactics should even be necessary. What if all state _wasn't_ global?

<Tweet id="1241756566048694272" />

## Local vs. global state

The first of [Redux's three principles](https://redux.js.org/introduction/three-principles) is that there is essentially a _single source of truth_ for your whole application state:

> The state of your whole application is stored in an object tree within a single store.
>
> _Source: [Redux's three principles: single source of truth](https://redux.js.org/introduction/three-principles#single-source-of-truth)_

The primary reason for this is that it makes many things _easier_, such as sharing data, rehydrating state, "time-travel debugging", etc. But it suffers from a fundamental disconnect: _there is no such thing as a single source of truth_ in any non-trivial application. All applications, even front-end apps, are distributed at some level:

<Tweet id="1116019772238454784" />

And, in a contradictory way, even the Redux Style Guide advises against putting the entire state of your application in a single store:

> [...] Instead, there should be a single place to find all values that you consider to be global and app-wide. Values that are "local" should generally be kept in the nearest UI component instead.
>
> _Source: [Redux Style Guide](https://redux.js.org/style-guide/style-guide/#evaluate-where-each-piece-of-state-should-live)_

Whenever something is done for the sole purpose of making something easy, it almost always makes some other use-case more difficult. Redux and its single-source-of-truth is no exception, as there are many problems that arise from fighting against the nature of front-end apps being "distributed" instead of an idealistic atomic, global unit:

- Multiple orthogonal concerns that need to be represented in the state somehow.

This is "solved" by using [`combineReducers`](https://redux.js.org/recipes/structuring-reducers/using-combinereducers).

- Multiple separate concerns that need to share data, communicate with each other, or are otherwise tangentially related.

This is "solved" by [more complex, custom reducers](https://redux.js.org/recipes/structuring-reducers/beyond-combinereducers) that orchestrate events through these otherwise separate reducers.

- Irrelevant state updates: when separate concerns are combined (using `combineReducers` or similar) into a single store, whenever any part of the state updates, the _entire_ state is updated, and every "connected" component (every subscriber to the Redux store) is notified.

This is "solved" by using [selectors](https://redux.js.org/introduction/learning-resources#selectors), and perhaps by using another library like [`reselect`](https://blog.isquaredsoftware.com/2017/12/idiomatic-redux-using-reselect-selectors/) for memoized selectors.

I put "solved" in quotes because these are all solutions that are all but necessary due to problems that are caused solely by using a global, atomic store. In short, having a single global store is unrealistic, even for apps that are already using global stores. Whenever you use a 3rd-party component, or local state, or local storage, or query parameters, or a router, etc., you have already shattered the illusion of a single global store. App data is always distributed at some level, so the natural solution should be to embrace the distribution (by using local state) rather than fighting against it just for the sake of making some use-cases easier to develop in the short run.

## Acting differently

So how can we address this global state problem? To answer that, we need to go back in time a little bit and take some inspiration from another old, well-established model: [the actor model](https://en.wikipedia.org/wiki/Actor_model).

The actor model is a surprisingly simple model that can be extended slightly beyond its original purpose (concurrent computation). In short, an actor is an entity that can do three things:

- It can receive messages (events)
- It can change its state/behavior as a reaction to a received message, including spawning other actors
- It can send messages to other actors

If you thought "hmm... so a Redux store is sort of an actor", congratulations, you already have a basic grasp of the model! A Redux store, which is based on some single combined-reducer thing:

- ✅ Can receive events
- ✅ Changes its state (and thus its behavior, [if you're doing it right](https://dev.to/davidkpiano/redux-is-half-of-a-pattern-1-2-1hd7)) as a reaction to those events
- ❌ Can't send messages to other stores (there's only one store) or between reducers (dispatching only happens outside-in).

It also can't really spawn other "actors", which makes the [Reddit example in the official Redux advanced tutorial](https://redux.js.org/advanced/async-actions) more awkward than it needs to be:

```js
function postsBySubreddit(state = {}, action) {
  switch (action.type) {
    case INVALIDATE_SUBREDDIT:
    case RECEIVE_POSTS:
    case REQUEST_POSTS:
      return Object.assign({}, state, {
        [action.subreddit]: posts(state[action.subreddit], action),
      });
    default:
      return state;
  }
}
```

_Source: https://redux.js.org/advanced/async-actions#reducersjs_

Let's dissect what is happening here:

1. We're taking only the relevant slice of state we need (`state[action.subreddit]`), which should ideally be its own entity
2. We are determining what the next state of only this slice should be, via `posts(state[action.subreddit], action)`
3. We are surgically replacing that slice with the updated slice, via `Object.assign(...)`.

In other words, there is no way we can dispatch or forward an event directly to a specific "entity" (or _actor_); we only have a single actor and have to manually update only the relevant part of it. Also, every other reducer in `combineReducers(...)` will get the entity-specific event, and even if they don't update, every single one of them will still be called for every single event. There's no easy way to optimize that. A function that isn't called is still much more optimal than a function that is called and ultimately does nothing (i.e., returns the same state), which happens most of the time in Redux.

## Reducers and actors

So how do reducers and actors fit together? Simply put, a reducer describes the behavior of an individual actor:

- Events are sent to a reducer
- A reducer's state/behavior can change due to a received event
- A reducer can spawn actors and/or send messages to other actors (via executed declarative actions)

This isn't a cutting-edge, groundbreaking model; in fact, you've probably been using the actor model (to some extent) without even knowing it! Consider a simple input component:

```jsx
const MyInput = ({ onChange, disabled }) => {
  const [value, setValue] = useState("");

  return (
    <input
      disabled={disabled}
      value={value}
      onChange={(e) => setValue(e.target.value)}
      onBlur={() => onChange(value)}
    />
  );
};
```

This component, in an implicit way, is sort of like an actor!

- It "receives events" using React's slightly awkward parent-to-child communication mechanism - prop updates
- It changes state/behavior when an event is "received", such as when the `disabled` prop changes to `true` (which you can interpret as some event)
- It can send events to other "actors", such as sending a "change" event to the parent by calling the `onChange` callback (again, using React's slightly awkward child-to-parent communication mechanism)
- In theory, it can "spawn" other "actors" by rendering different components, each with their own local state.

Reducers make the behavior and business logic more explicit, especially when "implicit events" become concrete, dispatched events:

```jsx
const inputReducer = (state, event) => {
  /* ... */
};

const MyInput = ({ onChange, disabled }) => {
  const [state, dispatch] = useReducer(inputReducer, {
    value: "",
    effects: [],
  });

  // Transform prop changes into events
  useEffect(() => {
    dispatch({ type: "DISABLED", value: disabled });
  }, [disabled]);

  // Execute declarative effects
  useEffect(() => {
    state.effects.forEach((effect) => {
      if (effect.type === "notifyChange") {
        // "Send" a message back up to the parent "actor"
        onChange(state.value);
      }
    });
  }, [state.effects]);

  return (
    <input
      disabled={disabled}
      value={state.value}
      onChange={(e) =>
        dispatch({
          type: "CHANGE",
          value: e.target.value,
        })
      }
      onBlur={() => dispatch({ type: "BLUR" })}
    />
  );
};
```

## Multi-Redux?

Again, one of Redux's three main principles is that Redux exists in a single, global, atomic source of truth. All of the events are routed through that store, and the single huge state object is updated and permeates through all connected components, which use their selectors and memoization and other tricks to ensure that they are only updated when they need to be, especially when dealing with excessive, irrelevant state updates.

And using a single global store has worked pretty well when using Redux, right? Well... not exactly, to the point that there are entire libraries dedicated to providing the ability to use Redux on a more distributed level, e.g., for [component state and encapsulation](https://redux.js.org/introduction/ecosystem#component-state-and-encapsulation). It is possible to use Redux at a local component level, but that was not its main purpose, and the official `react-redux` integration does not naturally provide that ability.

## No Redux?

There are other libraries that embrace the idea of "state locality", such as [MobX](https://mobx.js.org/README.html) and [XState](https://xstate.js.org/docs/). For React specifically, there is [Recoil](http://recoiljs.org/) for "distributed" state and the built-in [`useReducer` hook](https://reactjs.org/docs/hooks-reference.html#usereducer) that feels a lot like a local Redux, specifically for your component. For declarative effects, I created [`useEffectReducer`](https://github.com/davidkpiano/useeffectreducer) which looks and feels just like `useReducer`, but also gives you a way to manage effects.

For state that needs to be shared (not globally), you can use a pattern that is very similar to what React-Redux already uses, by making an object that can be subscribed to (i.e., "listened" to) and passed down through [context](https://reactjs.org/docs/hooks-reference.html#usecontext):

<Tweet id="1228700861024604160" />

That will give you the best performance, as that "subscribable" object will seldom/never change. If that feels a bit boilerplatey for you and performance is not a huge concern, you can combine `useContext` and `useReducer` with not too much effort:

```jsx
const CartContext = createContext();

const cartReducer = (state, event) => {
  // reducer logic
  // try using a state machine here! they're pretty neat

  return state;
};

const initialCartState = {
  // ...
};

const CartContextProvider = ({ children }) => {
  const [state, dispatch] = useReducer(cartReducer, initialCartState);

  return (
    <CartContext.Provider value={[state, dispatch]}>
      {children}
    </CartContext.Provider>
  );
};

export const useCartContext = () => {
  return useContext(CartContext);
};
```

And then use it in your components:

```jsx
const CartView = () => {
  const [state, dispatch] = useCartContext();

  // ...
};
```

Not too bad, right? In general, this is not a problem that can be solved in Redux without going against-the-grain, since Redux is fundamentally a single, atomic global store.

## What do others think?

I ran a non-scientific poll on Twitter to see where most app state lives, and how developers feel about it:

<Tweet id="1227615817640087553" />

![Global vs. Local State poll](https://dev-to-uploads.s3.amazonaws.com/i/lioo56gpviopcy2ccwqf.png)

From this, I gather two things:

- Whether you distribute state locally, or contain all state in a single store, you will be able to accomplish app state requirements successfully.
- However, more developers are discontent with the majority of app state being global instead of local, which also might hint to why the majority of developers are happy using local state instead.

What do you think? Share your thoughts in the comments!

## Conclusion

Thinking in terms of "actors", in which your application is organized by lots of smaller actors that all talk to each other by passing messages/events to each other, can encourage separation of concerns and make you think differently about how state should be localized (distributed) and connected. My goal for this post is to help you realize that not _all_ state needs to be global, and that other patterns (such as the Actor Model) exist for modeling distributed state and communication flow.

The Actor Model is not a panacea, though. If you're not careful, you can end up having a spaghetti-like state management problem, where you have completely lost track of which actor is talking to another actor. Anti-patterns are present in any solution that you choose, so it helps to research best practices and actually model your app before you start coding.

If you want to learn more about the Actor Model, check out [The Actor Model in 10 Minutes](https://www.brianstorti.com/the-actor-model/) by [Brian Storti](https://twitter.com/brianstorti), or any of these videos:

<Youtube id="ELwEdb_pD0k" />

<Youtube id="Vg60lf92EkM" />

Please keep in mind that this is post reflects my opinions based on what I've researched, and is in no way meant to be authoritative on the way you should do things. I want to make you _think_, and I hope that this post accomplished that goal. Thanks for reading!

If you enjoyed this post (or even if you didn't and just want to hear more of my state management ramblings), [subscribe to the Stately Newsletter](https://www.stately.dev/) for more content, thoughts, and discussion 📬

<Tweet id="1237091703087079425" />


Learn how Redux, and all other state management libraries, have one thing in common - they are all partial implementations of state machines - and how we can improve the way we model app state and logic.

Redux is half of a pattern (2/2)

Redux is half of a pattern (1/2)


[XState](https://github.com/davidkpiano/xstate) version 4.7 [has just been released](https://github.com/davidkpiano/xstate/releases/tag/v4.7.0). This is a minor version bump, but a major reworking of the internal algorithms, a lot of new capabilities, bug fixes, and a better TypeScript experience. It also paves the road for even more utilities, like `@xstate/test` and `@xstate/react`, as well as compatibility with other 3rd-party tools across the ecosystem, and even across languages.

## What is XState?

XState is a JavaScript (and TypeScript) library for creating state machines and statecharts, and interpreting them. State machines enforce a specific set of ”rules“ on logic structure such that:

- There are a finite number of **states** (such as `"loading"` or `"success"`), which is different than _context_ (related data with potentially infinite possibilities, such as `email` or `age`)
- There are a finite number of **events** (such as `{ type: 'FETCH', query: "..." }` that can trigger a transition between states.
- Each state has **transitions**, which say, ”Given some **event**, go to this next state and/or do these actions”.

You don’t need a state machine library to do this, as you can use `switch` statements instead:

```ts
    switch (state.status) {
      case 'idle': // finite state
        switch (event.type) {
          case 'FETCH':
            return {
              ...state,
              status: 'loading',
              query: event.query
            };
          // ...
        // ...
      // ...
    }
```

But let’s be honest, writing it like this is arguably a bit cleaner:

```ts
const machine = Machine({
  initial: "idle",
  states: {
    idle: {
      on: {
        FETCH: {
          target: "loading",
          actions: assign({ query: (_, event) => event.query }),
        },
      },
    },
    // ...
  },
});
```

And it also makes it possible to directly copy-paste this machine code into a visualizer, like [XState Viz](https://xstate.js.org/viz), and visualize it, like was done at the end of the [No, disabling a button is not app logic](https://dev.to/davidkpiano/no-disabling-a-button-is-not-app-logic-598i) article:

![State machine visualization on XState Viz](https://res.cloudinary.com/practicaldev/image/fetch/s--o5PbZ3py--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://thepracticaldev.s3.amazonaws.com/i/218tb91ltxrnv988owz0.png)
[View this viz on XState Viz](https://xstate.js.org/viz/?gist=414c0e4c40dab1dc80c9218f85605a24)

Then there are **statecharts**, which are an extension of finite state machines created by [David Harel in 1989 (read the paper 📑)](http://www.inf.ed.ac.uk/teaching/courses/seoc/2005_2006/resources/statecharts.pdf). Statecharts offer many improvements and mitigate many issues of using flat finite state machines, such as:

- Nested states (hierarchy)
- Parallel states (orthogonality)
- History states
- Entry, exit, and transition actions
- Transient states
- Activities (ongoing actions)
- Communication with many machines (invoked services)
- Delayed transitions
- And much more

These are things that you _definitely_ do not want to implement yourself, which is why libraries like XState exist. And this brings us to…

## What is new in XState 4.7?

This minor release has been worked on for months, with a huge amount of help from [Mateusz Burzyński (also known as AndaristRake)](https://twitter.com/AndaristRake) 👏. The reason it took so long was because we are internally reworking the algorithms to be simpler, fit the [SCXML spec](https://www.w3.org/TR/scxml/#InternalStructureofEvents), and be compatible with a growing number of tools in the ecosystem. This refactoring also makes adding new capabilities much easier, and will hopefully encourage more contributors to help with this project. As a nice side-effect, it also eliminates a few edge-case bugs that had workarounds, but might have caused a suboptimal developer experience in previous versions.

## Refactored internal algorithms

How difficult can it be to create a statechart library? A lot more difficult than it seems, especially if you want to conform to the long, but well-established [SCXML spec](https://www.w3.org/TR/scxml). There’s even libraries for integrating SCXML code directly with JavaScript, such as Jacob Beard’s excellent [SCION tools](http://scion.scxml.io/), which I highly recommend you check out. It was a huge inspiration for XState, and XState is tested against much of the same code.

SCXML specifies an [algorithm for SCXML interpretation](https://www.w3.org/TR/scxml/#AlgorithmforSCXMLInterpretation), which is written in pseudocode, but directly transferable to many popular languages. This algorithm was followed more closely in the refactor, which simplified a lot of the code base and removed the need for ad-hoc data structures such as `StateTree`, which was used to keep track of which state nodes were "active" for a given transition (now it’s just a set).

As a result, the core code base is a little smaller, the algorithms are a little bit faster (determining the next state is basically an O(1) lookup, O(n) worst-case), and the code base is a lot nicer to work with and contribute to. We will continue to improve the algorithms used as we move towards 5.0.

## Typestates

[Typestates](https://en.wikipedia.org/wiki/Typestate_analysis) are really useful for developers. They’re popular in Rust, and this article on [The Typestate Pattern in Rust](http://cliffle.com/blog/rust-typestate/) describes them elegantly:

> Typestates are a technique for moving **properties of state** (the dynamic information a program is processing) **into the type level** (the static world that the compiler can check ahead-of-time).

Without learning Rust or diving into the Wikipedia article, let’s present a classic example: loading data. You might represent the state’s context in this way:

```ts
interface User {
  name: string;
}

interface UserContext {
  user?: User;
  error?: string;
}
```

This type-safe declaration allows you to defensively program effectively, but it can be a bit annoying when you are 100% sure that `user` is defined:

```ts
if (state.matches("success")) {
  if (!state.context.user) {
    // this should be impossible!
    // the user definitely exists!
    throw new Error("Something weird happened");
  }

  return state.context.user.name;
}
```

In 4.7, XState allows you to [represent your states with Typestates](https://xstate.js.org/docs/guides/typescript.html#typestates) so that you can tell the compiler that you know how the `context` should be in any given state:

![GIF showing that the optional user object will be defined in the success state](https://res.cloudinary.com/practicaldev/image/fetch/s--GakogjRY--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_66%2Cw_880/https://thepracticaldev.s3.amazonaws.com/i/64d42j77op89yta9gbi8.gif)

This is very useful and improves the developer experience, but should be used as a strong guide, and not as a guarantee. It works by using [discriminated unions in TypeScript](https://basarat.gitbooks.io/typescript/docs/types/discriminated-unions.html) to define your states, but the way it is implemented requires TypeScript version 3.7 and higher. There’s still some quirks to work out, as we’re basically trying to trick TypeScript into knowing some extra information about our state machines that is otherwise difficult/impossible to infer in a statically typed language. (Maybe one day JavaScript will have a dependently-typed flavor.)

## Better service experience

XState makes invoking external ”services” a first-class citizen. If this is a foreign concept, for now, just understand that it answers the question “how can many state machines communicate with each other?”, and the answer is by using events as the main communication mechanism. In 4.7, the developer experience for this is improved:

- Invoked services can now be referenced on the `state.children` object by their ID. So if a state invokes some service with `id: 'fetchUser'`, then that invocation will be present on `state.children.fetchUser`.
- The new `forwardTo()` action creator allows you to forward events to invoked services, which cuts down a lot of boilerplate:

```ts
on: {
  SOME_EVENT: {
    actions: forwardTo("someService");
  }
}
```

- SCXML has this notion of a `sessionid`, which is a unique identifier for each invoked service. XState 4.7 becomes more SCXML-compatible by keeping a reference of this in `state._sessionid`, which corresponds to the SCXML `_sessionid` variable.
- XState can use that `_sessionid` to determine which service sent an event, so it can respond with an event back, using the new `respond()` action creator:

```ts
const authServerMachine = Machine({
  initial: "waitingForCode",
  states: {
    waitingForCode: {
      on: {
        CODE: {
          actions: respond("TOKEN", { delay: 10 }),
        },
      },
    },
  },
});

const authClientMachine = Machine({
  initial: "idle",
  states: {
    idle: {
      on: { AUTH: "authorizing" },
    },
    authorizing: {
      invoke: {
        id: "auth-server",
        src: authServerMachine,
      },
      entry: send("CODE", { to: "auth-server" }),
      on: {
        TOKEN: "authorized",
      },
    },
    authorized: {
      type: "final",
    },
  },
});
```

You can make your own custom action creators too, and implement patterns that you might be familiar with already if you’ve worked with microservices.

## Wildcard descriptors

If you’ve ever wanted to transition from a state if _any_ (unspecified) event is received? Well, you’re in luck, because XState now supports [wildcard descriptors](https://xstate.js.org/docs/guides/transitions.html#wildcard-descriptors), which are a type of [event descriptor (SCXML)](https://www.w3.org/TR/scxml/#EventDescriptors) that describes a transition for any event in a given state:

```ts
const quietMachine = Machine({
  id: "quiet",
  initial: "idle",
  states: {
    idle: {
      on: {
        WHISPER: undefined,
        // On any event besides a WHISPER, transition to the 'disturbed' state
        "*": "disturbed",
      },
    },
    disturbed: {},
  },
});

quietMachine.transition(quietMachine.initialState, "WHISPER");
// => State { value: 'idle' }

quietMachine.transition(quietMachine.initialState, "SOME_EVENT");
// => State { value: 'disturbed' }
```

## Much, much more

See [https://github.com/davidkpiano/xstate/releases/tag/v4.7.0](https://github.com/davidkpiano/xstate/releases/tag/v4.7.0) for an overview of the latest updates in this minor version.

## The future of XState

All this leads to the big question: what are the future plans/goals for XState? The first important thing to realize is that XState is _not just another state management library_, and state management was never its only goal. XState strives to bring two things to the JavaScript ecosystem:

- **State machines/statecharts**, for modeling the logic of any individual component
- **Actor model**, for modeling how components communicate with each other and behave in a system

All of these are very old, very useful, and battle-tested concepts. The benefits they provide cannot be understated, and highlight the future plans for XState and related tooling:

- Better visualization tools, including an updated visualizer, dev tools for Firefox and Chrome (work in progress!), dev tools for VS Code, and integration with other graphical viz tools such as [PlantUML](https://plantuml.com/) and [GraphViz](https://www.graphviz.org/)
- Full [SCXML](https://www.w3.org/TR/scxml/) compatibility, which will allow statecharts authored in XState to be reusable in other languages that have SCXML tooling, as it is a truly language-agnostic spec
- A catalog of examples, to demonstrate common patterns and best practices for many use-cases
- Analytics, testing, and simulation tools

As well as some initial ideas for XState version 5.0:

- Better type safety and a more seamless TypeScript experience
- Static analysis tools for compile-time hints/warnings and run-time optimizations
- A more ”functional”, and completely optional, syntax for defining states and transitions more naturally (developer experience)
- Higher-level state types such as `"task"` and `"choice"` to make it easier to define workflows and remove some boilerplate

We’re also listening to ideas that you present to us in the [XState Wish List](https://spectrum.chat/statecharts/general/xstate-wish-list~6f025b10-fcbc-4ab5-ae59-5201112f06f2) thread, so post what you would like to see!

## More information

If you’re curious about XState or statecharts in general, there are many fantastic resources, including:

- [The World of Statecharts](https://statecharts.github.io/) by Erik Mogensen
- [Statecharts community](https://spectrum.chat/statecharts) on Spectrum
- [XState docs](https://xstate.js.org/docs)
- [Other tutorials](https://xstate.js.org/docs/about/tutorials.html) made by many excellent developers in the community


XState version 4.7 has just been released. This is a minor version bump, but a major reworking of the internal algorithms, a lot of new capabilites, bug fixes and a better TypeScript experience.

XState: version 4.7 and the future

Disabling a button is not logic. Rather, it is a sign that logic is fragile and bug-prone. Let’s explore this with a simple example: fetching data in a React component.

Engineering Blog