Installation

Get @statewalker/fsm running in your project.

Installing via npm

The recommended way to use StateWalker is through npm. This gives you the full library with type definitions and keeps it under your project’s dependency management:

npm install @statewalker/fsm

The @statewalker/fsm package contains everything you need to define and run state machines. It has no runtime dependencies.

Using a CDN

When you are prototyping or building a plain HTML page, you can skip the build step and import StateWalker straight from a CDN:

<script type="module">
  import { FsmProcess } from "https://unpkg.com/@statewalker/fsm";

  // Your code here
</script>

Any npm CDN that serves ES modules works — for example https://cdn.jsdelivr.net/npm/@statewalker/fsm. This loads the module directly in the browser with no bundler.

Verifying the installation

Before building anything, confirm the package resolves. Create a small file that imports the engine and runs a one-state machine:

// test.js
import { FsmProcess } from "@statewalker/fsm";

const process = new FsmProcess({ key: "Ready" });
process.onStateCreate((state) => {
  state.onEnter(() => console.log("Entered:", state.key));
});
await process.dispatch("");

Run it with Node:

node test.js

When you see Entered: Ready in the console, StateWalker is installed and working.

What you import

Everything is exported from the package root. The three things you will reach for most:

• FsmProcess — the state machine engine. You construct it with a config and drive it with dispatch(event).
• startProcess — the ergonomic runner that installs per-state behaviour for you.
• setProcessTracer — a one-line way to trace the machine as it moves.

The configuration you pass to FsmProcess is fully typed. The core shape is just three fields:

import type { FsmStateConfig } from "@statewalker/fsm";

const config: FsmStateConfig = {
  key: "Toggle",
  transitions: [
    ["", "*", "Off"],       // enter the initial state
    ["Off", "flip", "On"],
    ["On", "flip", "Off"],
  ],
  states: [
    { key: "Off" },
    { key: "On" },
  ],
};

A state needs only a key; transitions and nested states are optional. TypeScript validates the shape as you write it, catching missing keys and malformed tuples.

Next steps

Now that the package is installed, build your first machine in the Quick Start, or go straight to Getting Started for a step-by-step tour of the engine API.