Getting started with XState

XState is a state management and orchestration solution for javascript and typescript.

XState is not dependent on any frontend or backend framework, but instead a zero-dependencies solution for any typescript app.

The core building blocks of XState are:

• Event-driven
• Actor model
• State machines (State charts)

In this course we will be focusing more on the practice of how to use XState in real scenarios, and less on the overall theory around its model.

We will learn more details about the XState model only when required to understand a specific implementation.

For a more general overview of how XState, state charts, and the actor model work you can check out the official documentation.

Installing XState

The only dependency needed to start using XState is xstate (core):

pnpm add xstate

This course is based on the latest version of XState: v5

I use pnpm as package manager.

XState then provides helper libraries to integrate with specific frameworks. In this course we will learn XState in the context of react.

We therefore install also @xstate/react:

pnpm add @xstate/react

Keep in mind that the integration is similar for other frameworks. React is just a reference, but the core details are framework agnostic.

I suggest keeping the course repository as reference as you go through the course.

The course's repository uses vite as build tool and react-router-dom for routing. Each route contains a different example covered in the course.

These are the dependencies inside package.json:

{
  "name": "xstate-complete-getting-started-guide",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "tsc": "tsc -b"
  },
  "dependencies": {
    "@xstate/react": "^4.1.1",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-router-dom": "^6.25.1",
    "xstate": "^5.16.0"
  },
  "devDependencies": {
    "@types/react": "^18.3.3",
    "@types/react-dom": "^18.3.0",
    "@vitejs/plugin-react": "^4.3.1",
    "typescript": "^5.5.4",
    "vite": "^5.3.4"
  }
}

Enough with preparation, let's jump into the first example! 🚀