Skip to content
statelyaiPublic

About

Inspect state transitions and actor communication

Resources

Code of conduct

Contributing

Stars

85 stars

Watchers

4 watching

Forks

Repository files navigation

Stately.ai Inspect

Legacy package

@statelyai/inspect is the legacy inspection package for existing XState v5 integrations. Its current APIs and releases remain available. For new projects and XState v6, use createInspector from @statelyai/sdk/inspect:

npm install @statelyai/sdk

By default, the SDK sends inspection events to the Stately-hosted relay at wss://sky.stately.ai. Treat the logged inspectorUrl as a private access link and share it only with intended viewers. To use a self-hosted SDK relay, pass its URL with createInspector({ url }).

import { createActor } from 'xstate';
import { createInspector } from '@statelyai/sdk/inspect';
import { machine } from './someMachine';

const inspector = createInspector();
const actor = createActor(machine, { inspect: inspector.inspect });
actor.start();

await inspector.ready;
console.log(inspector.inspectorUrl);

The SDK does not open a browser automatically and omits snapshot context by default. It is not a drop-in replacement for this package. Read Migrate to SDK inspection before migrating factories, options, manual inspection, or transports. There is no compatibility wrapper.

The sections below document the existing legacy APIs.

The @statelyai/inspect package enables developers to visually inspect state transitions and actor communication in any JavaScript/TypeScript app.

Documentation: stately.ai/docs/inspector

Features

  • Visualize state machines
  • Visualize sequence diagrams
  • Works best with XState
  • Can be used with any framework or library (or none at all)
  • Works in Node.js via WebSocket

Installation

npm install @statelyai/inspect

Usage

Browser inspector with XState

import { createBrowserInspector } from '@statelyai/inspect';
import { createActor } from 'xstate';
import { machine } from './someMachine';

const inspector = createBrowserInspector();

const actor = createActor(machine, {
  inspect: inspector.inspect,
});

actor.start();

Browser inspector with anything

import { createBrowserInspector } from '@statelyai/inspect';

const inspector = createBrowserInspector();

// ...

inspector.actor('someActor', {
  status: 'active',
  context: {
    /* any context data */
  },
});

inspector.actor('anotherActor');

inspector.event('someActor', 'hello', { source: 'anotherActor' });

inspector.snapshot('anotherActor', {
  status: 'active',
  context: {
    /* any context data */
  },
});

Node.js (WebSocket)

Use createInspectorServer and createWebSocketInspector to inspect state machines running in Node.js. The server opens the Stately inspector in your browser and relays events from your app to it.

import { createWebSocketInspector } from '@statelyai/inspect';
import { createInspectorServer } from '@statelyai/inspect/server';
import { createActor } from 'xstate';
import { machine } from './someMachine';

// 1. Start the relay server (opens browser automatically)
const server = createInspectorServer();

// 2. Create the inspector
const inspector = createWebSocketInspector({
  url: 'ws://localhost:8080',
});

// 3. Connect your actors
const actor = createActor(machine, {
  inspect: inspector.inspect,
});

actor.start();

Server options

createInspectorServer({
  port: 8080, // default
  url: 'https://stately.ai/inspect', // inspector UI URL
  autoOpen: true, // open browser automatically
});

Without XState

import { createWebSocketInspector } from '@statelyai/inspect';
import { createInspectorServer } from '@statelyai/inspect/server';

const server = createInspectorServer();
const inspector = createWebSocketInspector();

inspector.actor('myActor', { status: 'active', context: { count: 0 } });
inspector.event('myActor', { type: 'INCREMENT' });
inspector.snapshot('myActor', { status: 'active', context: { count: 1 } });

WebSocket inspector options

createWebSocketInspector({
  url: 'ws://localhost:8080', // default
  filter: (event) => true, // filter which events to send
  serialize: (event) => event, // custom serialization
  autoStart: true, // auto-connect on creation
  sanitizeEvent: (event) => event, // remove sensitive event data
  sanitizeContext: (ctx) => ctx, // remove sensitive context data
});

About

Inspect state transitions and actor communication

Resources

Code of conduct

Contributing

Stars

85 stars

Watchers

4 watching

Forks

Releases

Packages

Used by

Contributors

Languages