@xstate/inspect

What is @xstate/inspect?

@xstate/inspect is a tool for visualizing, inspecting, and debugging XState state machines and statecharts. It provides a way to see the current state, events, and transitions of your state machines in real-time, which can be extremely helpful for development and debugging purposes.

What are @xstate/inspect's main functionalities?

Real-time Inspection

This feature allows you to inspect the state machine in real-time. By using the `inspect` function, you can open a new window or an iframe that shows the current state, events, and transitions of your state machine.

import { inspect } from '@xstate/inspect';

inspect({
  iframe: false // open in new window
});

// Then, use the inspect service in your XState machine
import { createMachine, interpret } from 'xstate';

const toggleMachine = createMachine({
  id: 'toggle',
  initial: 'inactive',
  states: {
    inactive: { on: { TOGGLE: 'active' } },
    active: { on: { TOGGLE: 'inactive' } }
  }
});

const service = interpret(toggleMachine, { devTools: true }).start();

Event Logging

This feature logs events and state transitions to the console, which can be useful for debugging and understanding the flow of your state machine.

import { inspect } from '@xstate/inspect';

inspect({
  iframe: false // open in new window
});

import { createMachine, interpret } from 'xstate';

const toggleMachine = createMachine({
  id: 'toggle',
  initial: 'inactive',
  states: {
    inactive: { on: { TOGGLE: 'active' } },
    active: { on: { TOGGLE: 'inactive' } }
  }
});

const service = interpret(toggleMachine, { devTools: true }).onTransition((state) => {
  console.log(state.value);
}).start();

State Visualization

This feature provides a visual representation of your state machine, showing the current state, possible transitions, and events. This can be extremely helpful for understanding and debugging complex state machines.

import { inspect } from '@xstate/inspect';

inspect({
  iframe: false // open in new window
});

import { createMachine, interpret } from 'xstate';

const toggleMachine = createMachine({
  id: 'toggle',
  initial: 'inactive',
  states: {
    inactive: { on: { TOGGLE: 'active' } },
    active: { on: { TOGGLE: 'inactive' } }
  }
});

const service = interpret(toggleMachine, { devTools: true }).start();

// The state visualization will be available in the new window or iframe

Other packages similar to @xstate/inspect

redux-devtools

Redux DevTools is a set of tools to help with debugging Redux applications. It provides a way to inspect the state and actions of your Redux store in real-time, similar to how @xstate/inspect works for XState state machines. However, Redux DevTools is specifically designed for Redux and does not support XState state machines.

mobx-devtools

MobX DevTools is a set of tools for inspecting and debugging MobX applications. It provides real-time inspection of the state and actions in your MobX store, similar to @xstate/inspect for XState. However, it is specifically designed for MobX and does not support XState state machines.

reactotron

Reactotron is a desktop app for inspecting and debugging React and React Native applications. It provides real-time inspection of state, actions, and network requests, similar to @xstate/inspect. However, it is more general-purpose and not specifically designed for XState state machines.

README

@xstate/inspect

Inspection tools for XState.

• XState (Vanilla)
• XState + TypeScript
• XState + Vue
• XState + React

See CodeSandbox example here

Installation

1. Install with npm or yarn:

npm install @xstate/inspect
# or yarn add @xstate/inspect

1. Import it at the beginning of your project, before any other code is called:

import { inspect } from '@xstate/inspect';

inspect({
  // options
  // url: 'https://statecharts.io/inspect', // (default)
  iframe: false // open in new window
});

1. Add { devTools: true } to any interpreted machines you want to visualize:

import { interpret } from 'xstate';
import { inspect } from '@xstate/inspect';
// ...

const service = interpret(someMachine, { devTools: true });

Inspect Options

// defaults
inspect({
  iframe: () => document.querySelector('iframe[data-xstate]'),
  url: 'https://statecharts.io/inspect'
});

// the above is the same as this:
inspect();

Arguments: the options object passed to inspect(options) with the following optional properties:

• iframe (function or iframe Element or false) - resolves to the iframe element to display the inspector in. If this is set to iframe: false, then a popup window will be used instead.

  ⚠️ Note: you might need to allow popups to display the inspector in a popup window, as they might be blocked by the browser by default.

  By default, the inspector will look for an <iframe data-xstate> element anywhere in the document. If you want to target a custom iframe, specify it eagerly or lazily:

  // eager
  inspect({
    iframe: document.querySelector('iframe.some-xstate-iframe')
  });
  

  // lazy
  inspect({
    iframe: () => document.querySelector('iframe.some-xstate-iframe')
  });
  

• url (string) - the URL of the inspector to connect to. By default, the inspector is running on http://statecharts.io/inspect.

Returns: an inspector object with the following properties:

• disconnect (function) - a function that disconnects the inspector and cleans up any listeners.

Implementing

You can implement your own inspector by creating a receiver. A receiver is an actor that receives inspector events from a source (like a parent window or a WebSocket connection):

• "service.register"

  {
    type: 'service.register';
    machine: StateMachine<any, any, any>;
    state: State<any, any>;
    id: string;
    sessionId: string;
    parent?: string;
    source?: string;
  }
  

• "service.stop"

  {
    type: 'service.stop';
    sessionId: string;
  }
  

• "service.state"

  {
    type: 'service.state';
    state: State<any, any>;
    sessionId: string;
  }
  

• "service.event"

  {
    type: 'service.event';
    event: SCXML.Event<any>;
    sessionId: string
  };
  

To listen to events from an inspected source, create a receiver with the appropriate create*Receiver(...) function; for example:

import { createWindowReceiver } from '@xstate/inspect';

const windowReceiver = createWindowReceiver(/* options? */);

windowReceiver.subscribe((event) => {
  // here, you will receive "service.*" events
  console.log(event);
});

You can also send events to the receiver:

// ...

// This will send the event to the inspected service
windowReceiver.send({
  type: 'xstate.event',
  event: JSON.stringify({ type: 'someEvent' }),
  service: /* session ID of the service this event is sent to */
});

The typical inspection workflow is as follows:

1. The inspect(/* ... */) call on the client opens the inspector (e.g., in a separate window, or creates a WebSocket connection)
2. The receiver sends an "xstate.inspecting" event to the client
3. The client sends "service.register" events to the receiver
4. An inspector listening to the receiver (via receiver.subscribe(...)) registers the machine (event.machine) by its event.sessionId
5. The machine is visually rendered, and its current state (event.state) is highlighted
6. As the service at the source receives events and changes state, it will send the receiver "service.event" and "service.state" events, respectively
7. The inspector can use those events to highlight the current state and keep a log of events sent to that service
8. When the service stops, a "service.stop" event is sent to the receiver with the event.sessionId to identify the stopped service.

FAQs

• How do I run the inspector in a NextJS app?

  Ensure that the inspector code only runs on the client, rather than the server:

  if (typeof window !== 'undefined') {
    inspect({
      /* options */
    });
  }