XState
kotick/xstate connects XState v5 machines to kotick. It exports all the functions of @xstate/react, with the same names and signatures. Thus, the change to your components is an import.
The adapter uses the xstate and @xstate/react of your app. kotick does not install them. Refer to Requirements for the versions.
Quick start
-
Install
kotick,xstateand@xstate/react, and mount<Kotick />once, as Installation shows. -
Import the XState hooks from
kotick/xstateinstead of@xstate/react: -
If the app creates actors outside React, wrap them with
connect(), as Actors outside React shows. -
Use the app until the machine is in a second state. The panel lists every state, and an R mark shows each state that you visited.
-
Select a state in the panel. The components show that state in place. Select it again to release it.
Actors outside React
Actors that you create outside React, for example in a module, need one more step. Wrap them with connect():
Use the actor that connect() returns everywhere in the app, for example with useSelector(sessionActor, …).
Prevent imports from @xstate/react
A component that imports a hook from @xstate/react continues to work, but the panel does not list its machine. To find these imports, add the no-restricted-imports rule to your linter. kotick/xstate exports all the functions of @xstate/react, so the rule can block the full package. For ESLint:
Oxlint has the same rule, with the same options.
Nested and parallel states
A state of an XState machine can contain child states. A state without child states is a leaf. kotick identifies a state by the dot path to its leaf, such as payment.error:
checkout is a parallel machine. A parallel machine is in one leaf of each region at the same time, for example shipping.express and payment.error. The panel shows the tree, and the keys of a fixture set are these leaf ids.
Previews
The rules in Previews apply. An XState machine adds these:
- The preview is a real XState snapshot.
matches(),hasTag(),can()andstatuswork as usual. - In a parallel machine, the regions that you did not touch keep their real state.
- The real actor continues to run. Timers, invoked promises and callbacks continue in it.
- A state without a recording or a fixture uses the live context. kotick logs a warning, because the live context often does not agree with the state. To give the state its own context, visit it in the app or write a fixture for it.
- Events from machines are blocked too. The events that
sendTo(),forwardTo()and delayed events send to a previewed actor go to the event log, as the events from the UI do.
Child actors
Machines that a machine invokes or spawns are listed under their parent. You can see their state, but you cannot preview them in this version.
The debug option
The hooks and createActorContext take one more option, debug. connect() takes the same object as its second argument. Use it to change how the panel shows an actor:
- To give an instance a name in the panel, set
label. This helps when a machine has more than one instance. - To give a machine an id that its definition does not have, set
id. The panel, the recordings and the fixtures then find the machine by this id. - To keep an actor out of kotick, set
disabled: true.
Give each machine an id in its definition when you can. Without one, kotick makes an id from the states and the context keys of the machine. That id changes when you add or remove states or context keys. Refer to The debug option for the type, and for what XState does with debug in production builds.
Production builds
In production builds, the hooks of kotick/xstate are the hooks of @xstate/react, and connect() returns the actor that you give it. The bundler removes the rest of the adapter. Refer to Choose an adapter for the size that the adapter adds.
Performance in development
When the panel is closed, the overlay itself costs almost nothing. The adapter costs a little more. It registers each actor, records its context, and passes snapshots through a proxy. These numbers are from the benchmarks in bench/, in jsdom with StrictMode. Compare the rows, not the absolute times.
| Work | @xstate/react | kotick/xstate |
|---|---|---|
A transition that renders a useMachine component again | 27 µs | 34 µs |
Mount and unmount 50 rows, each with useMachine | 1.0 ms | 2.1 ms |
100 events to an actor outside React (connect()) | 0.17 ms | 0.22 ms |
Thus, a transition costs approximately 8 µs more, a mount approximately 22 µs more, and an event to a connect()ed actor less than 1 µs more. Production builds do not have this cost.
How the adapter works
The adapter gives your components a proxy of each actor. The hooks call the hooks of @xstate/react, and return a proxy of the actor that they make. connect() does the same for an actor that you create outside React. The proxy sends each call to the real actor. During a preview, getSnapshot(), subscribe() and send() work differently.
A preview is a snapshot that XState makes. When you select a leaf, the registry keeps an override for that instance: the leaves and a context. The proxy gives the leaves and the context to machine.resolveState(), and returns that snapshot from getSnapshot() and to subscribers. The components render again with a real XState snapshot, so matches(), hasTag() and can() work. In a parallel machine, the regions that you did not select keep their current leaf. The live child actors are copied into the preview. The real actor does not know about the preview, and continues to run.
Events go to a log during a preview. send() on the proxy, and the internal send that sendTo(), forwardTo() and delayed events use, look for an override first. If there is one, the event goes to the event log of the panel, not to the actor.