Installation

Get StateWalker up and running in your project.

Installing via NPM

The recommended way to use StateWalker is through NPM. This gives you the full library with all its features and keeps your project dependencies managed:

npm install @statewalker/fsm

The @statewalker/fsm package contains everything you need to define and run state machines in your application.

Using a CDN for Browser Projects

When you’re prototyping or building a simple browser-based project, you can skip the build step entirely and load StateWalker directly from a CDN. This approach works great for quick experiments and HTML-based applications:

<script type="module">
  import { startProcesses } from 'https://cdn.skypack.dev/@statewalker/fsm';

  // Your code here
</script>

This loads the module directly in the browser, giving you immediate access to StateWalker’s functionality without any build configuration.

Setting Up Your Project

Once you’ve installed StateWalker, you’ll want to organize your code in a way that keeps things manageable as your application grows. A typical project structure separates your FSM configuration from your handler functions:

my-project/
├── src/
│   ├── index.js          # Entry point
│   ├── core/
│   │   └── index.js      # FSM configuration
│   ├── handlers/
│   │   └── index.js      # Business logic handlers
│   └── views/
│       └── index.js      # Presentation logic
└── package.json

This structure puts your main entry point in index.js, keeps your FSM definitions in the core directory, organizes your handler functions in handlers, and separates presentation logic in views. This layered approach makes it easy to test business logic independently of UI concerns.

Verifying the Installation

Before diving into building state machines, confirm that everything is working. Create a simple test file that imports StateWalker:

// test.js
import { startProcesses } from '@statewalker/fsm';

console.log('StateWalker installed successfully!');

Run it with Node:

node test.js

When you see “StateWalker installed successfully!” in your console, you’re ready to start building state machines.

Adding TypeScript Support

StateWalker includes TypeScript type definitions out of the box. When you’re working with TypeScript, you can import type definitions to get full autocomplete and type checking:

export type FsmConfig = {
  key: string;
  states?: FsmConfig[];
  transitions: [
    from: string,
    event: string,
    to: string
  ][];

  description?: string;
  events?: string[];
};

const config: FsmConfig = {
  key: "MyApp",
  transitions: [
    ['', '*', 'Ready'],
    ['Ready', 'start', 'Running'],
    ['Running', 'stop', 'Ready']
  ],
  states: [
    {
      key: 'Ready',
      description: 'Application ready to start',
      events: ['start']
    },
    {
      key: 'Running',
      description: 'Application is running',
      events: ['stop']
    }
  ]
};

The type system will validate your FSM configuration as you write it, catching common errors like missing required fields or invalid state references.

Optional Development Tools

For a smoother development experience, you might want to add a few additional tools. Vite provides fast development builds and hot module replacement, while TypeScript adds static type checking:

# Build tools
npm install --save-dev vite

# TypeScript
npm install --save-dev typescript @types/node

These tools aren’t required to use StateWalker, but they can make your development workflow faster and catch errors earlier.

Next Steps

Now that StateWalker is installed, let’s build your first application and see how state machines work in practice.

Continue to the Quick Start guide to create your first state machine.

For advanced project setup and configuration, explore the documentation on project structure, testing strategies, and deployment options.