@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.

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 */
    });
  }