Skip to content
XMachines

Installation

This guide covers installing XMachines packages in your project across different package managers and environments.

Prerequisites

Before installing XMachines, ensure you have:

  • Node.js 22+ (or compatible runtime)
  • Package manager: npm, pnpm, or yarn
  • TypeScript (optional but recommended for full type safety)

Installing XMachines

Choose your preferred package manager:

npm

Terminal window
npm install @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals

pnpm

Terminal window
pnpm add @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals

yarn

Terminal window
yarn add @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals

Package Selection Guide

XMachines consists of 8 modular packages. Choose the packages based on your needs:

Core Packages (Required)

@xmachines/play

  • Foundation package with core protocols and contracts
  • Required by all other packages

@xmachines/play-actor

  • Abstract actor base class extending XState Actor
  • Required for instantiating state machines

@xmachines/play-signals

  • TC39 Signals polyfill for reactive updates
  • Required for reactive state observation

@xmachines/play-xstate

  • XState v5 logic adapter with catalog binding
  • Required for state machine definitions

Minimal installation:

Terminal window
npm install @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals

UI and Routing (Optional)

@xmachines/play-ui

  • UI schema protocol with Zod validation
  • Install if: Building declarative UI structures from state

@xmachines/play-router

  • Route tree protocol and machine crawler
  • Install if: Implementing logic-driven routing

@xmachines/play-tanstack-react-router

  • TanStack Router adapter with signal observation
  • Install if: Using TanStack Router for navigation

@xmachines/play-react

  • React view renderer with JSON-Render
  • Install if: Building React applications

@xmachines/play-catalog

  • State machine catalog and registry patterns
  • Install if: Managing multiple machines with type inference

Complete Installation

For full-featured development with React and routing:

Terminal window
npm install @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals @xmachines/play-ui @xmachines/play-router @xmachines/play-tanstack-react-router @xmachines/play-react @xmachines/play-catalog

See also: API Reference for detailed descriptions of each package.

Environment-Specific Setup

Browser (Vite, Webpack, or other bundlers)

No special configuration needed. ESM imports work out of the box:

import { createMachine } from "@xmachines/play-xstate";
import { createActor } from "@xmachines/play-actor";
import { signal } from "@xmachines/play-signals";

Most modern bundlers (Vite, Webpack 5+, Rollup) handle ESM packages automatically.

Node.js

XMachines uses ESM (ECMAScript Modules) exclusively. Ensure your project is configured for ESM:

Option 1: Set "type": "module" in package.json

{
  "type": "module",
  "dependencies": {
    "@xmachines/play": "^1.0.0"
  }
}

Option 2: Use .mjs file extensions

Alternatively, name your files with .mjs extension:

Terminal window
node my-app.mjs

Import example:

import { createMachine } from "@xmachines/play-xstate";
import { createActor } from "@xmachines/play-actor";


const machine = createMachine({
  id: "example",
  initial: "idle",
  states: {
    idle: { on: { START: "running" } },
    running: { on: { STOP: "idle" } },
  },
});


const actor = createActor(machine);
actor.start();

Deno

XMachines works with Deno via npm specifiers:

import { createMachine } from "npm:@xmachines/play-xstate";
import { createActor } from "npm:@xmachines/play-actor";
import { signal } from "npm:@xmachines/play-signals";

Alternatively, use a CDN like esm.sh:

import { createMachine } from "https://esm.sh/@xmachines/play-xstate";

TypeScript

XMachines is written in TypeScript and includes built-in type definitions. No separate @types package is needed.

Recommended tsconfig.json settings:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": false,
    "resolveJsonModule": true
  }
}

Key settings:

  • moduleResolution: "bundler" (recommended) or "node16" for Node.js projects
  • strict: true enables full type checking
  • target: "ESNext" leverages modern JavaScript features

Type inference:

XMachines provides full type inference from machine catalog through to components:

import { createMachine } from "@xmachines/play-xstate";


const machine = createMachine({
  id: "typed",
  initial: "idle",
  context: { count: 0 },
  states: {
    idle: { on: { START: "running" } },
    running: { on: { STOP: "idle" } },
  },
});


// TypeScript infers exact state types
type States = typeof machine.states; // "idle" | "running"

Verifying Installation

Test your installation with this simple script:

test.ts (or test.js with "type": "module"):

import { createMachine } from "@xmachines/play-xstate";
import { createActor } from "@xmachines/play-actor";


const machine = createMachine({
  id: "test",
  initial: "ready",
  states: {
    ready: {},
  },
});


const actor = createActor(machine);
actor.start();


console.log("✓ XMachines installed successfully");
console.log("Current state:", actor.getSnapshot().value);

Run the test:

Terminal window
# TypeScript (requires tsx or ts-node)
npx tsx test.ts


# Or compile first
npx tsc test.ts && node test.js


# JavaScript (with "type": "module")
node test.js

Expected output:

✓ XMachines installed successfully
Current state: ready

Troubleshooting

Module Not Found

Error: Cannot find module '@xmachines/play-xstate'

Solutions:

  • Verify package is installed: npm list @xmachines/play-xstate
  • Re-install dependencies: npm install
  • Check node_modules/@xmachines/ directory exists

ESM Import Errors

Error: SyntaxError: Cannot use import statement outside a module

Solutions:

  • Add "type": "module" to package.json
  • Or rename files to .mjs extension
  • Or use dynamic import: const { createMachine } = await import('@xmachines/play-xstate')

Type Errors

Error: Could not find a declaration file for module '@xmachines/play-xstate'

Solutions:

  • Types are built-in; no @types package needed
  • Check TypeScript version (4.5+ required)
  • Verify moduleResolution in tsconfig.json is set correctly
  • Try npm install again to ensure types are properly linked

Version Mismatches

Error: Type incompatibilities between packages

Solution: Install all XMachines packages with matching major versions:

Terminal window
npm install @xmachines/play@latest @xmachines/play-xstate@latest @xmachines/play-actor@latest @xmachines/play-signals@latest

Next Steps

Now that XMachines is installed, you’re ready to build your first state machine:

Need help? Check the API Reference for detailed information.