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
- Autocomplete — context-aware suggestions for targets, actions, guards, events
- Code lenses — inline transition summaries, usage counts, diagram links
- Diagnostics — invalid targets, unused actions/guards, dead-end states, unreachable states, and more
- 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
| Setting |
Values |
Description |
xstate-lens.trace.server |
off, messages, verbose |
Trace communication with the language server |
License
Apache-2.0
Links
| |
