@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/sdkBy 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
- 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
npm install @statelyai/inspectimport { createBrowserInspector } from '@statelyai/inspect';
import { createActor } from 'xstate';
import { machine } from './someMachine';
const inspector = createBrowserInspector();
const actor = createActor(machine, {
inspect: inspector.inspect,
});
actor.start();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 */
},
});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();createInspectorServer({
port: 8080, // default
url: 'https://stately.ai/inspect', // inspector UI URL
autoOpen: true, // open browser automatically
});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 } });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
});