XState Lens

VS Code extension for distributed XState v5 state machines — machines split across multiple files (machine.ts, types.ts, context.ts, states/*.ts, etc.).

Existing tools only parse a single file. XState Lens follows imports across file boundaries to reconstruct the full machine from all of its parts.

Features

• Auto-discovery — finds machine directories in your workspace automatically
• Interactive diagram — visualize machines with auto-layout, simulation mode, and multi-machine drill-in navigation
• Go-to-Definition — Ctrl/Cmd-click on state names, actions, guards, actors, or events to jump to their definition across files
• Hover tooltips — state type, transitions, action kind, guard logic
• Code lenses — inline transition summaries, usage counts, diagram links
• Explorer tree — sidebar view of all machines with their states, actions, guards, actors, and events

What Machines Does It Support?

XState Lens works with machines that follow this directory convention:

SomeMachine/
  machine.ts        # setup().createMachine({ id, initial, states })
  types.ts          # StateName const
  context.ts        # MachineContext interface
  events.ts         # Event type union
  actions.ts        # assign(), raise(), emit() exports
  guards.ts         # Guard functions
  states/
    idle.ts         # export const idleState = { on: { ... } }
    loading.ts
  actors/
    fetchData.ts    # export const fetchData = fromPromise(...)

Getting Started

Install from the VS Code Marketplace, then open a workspace that contains distributed XState machines. The extension activates automatically.

• Status bar — shows the count of discovered machines
• Activity bar — click the XState Lens icon for the machine tree view
• Command palette — XState Lens: Show Machine Diagram to visualize a machine
• Command palette — XState Lens: Refresh Machine Discovery to re-scan

Requirements

VS Code >= 1.85.0

Configuration