# XState Connect XState v5 machines through kotick/xstate, and preview each state in place. `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. ```ts import { connect, defineFixtures, useMachine, useSelector } from 'kotick/xstate'; ``` The adapter uses the `xstate` and `@xstate/react` of your app. kotick does not install them. Refer to [Requirements](/docs/install#requirements) for the versions. ## Quick start 1. Install `kotick`, `xstate` and `@xstate/react`, and mount `` once, as [Installation](/docs/install#quick-start) shows. 2. Import the XState hooks from `kotick/xstate` instead of `@xstate/react`: ```diff - import { useMachine, useSelector, createActorContext } from '@xstate/react'; + import { useMachine, useSelector, createActorContext } from 'kotick/xstate'; ``` 3. If the app creates actors outside React, wrap them with `connect()`, as [Actors outside React](/docs/xstate#actors-outside-react) shows. 4. 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. 5. 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()`: ```ts import { createActor } from 'xstate'; import { connect } from 'kotick/xstate'; import { sessionMachine } from '@/machines/session'; export const sessionActor = connect(createActor(sessionMachine).start(), { id: 'session' }); ``` 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: ```js // eslint.config.js export default [ { rules: { 'no-restricted-imports': [ 'error', { name: '@xstate/react', message: 'Import the XState hooks from kotick/xstate, so that the panel lists the machine.', }, ], }, }, ]; ``` 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 ├── shipping │ ├── standard │ └── express └── payment ├── editing ├── processing ├── error └── success ``` `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](/docs/concepts#previews) apply. An XState machine adds these: - **The preview is a real XState snapshot.** `matches()`, `hasTag()`, `can()` and `status` work 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](/docs/fixtures) 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`. ```ts const [snapshot, send] = useMachine(checkoutMachine, { input, debug: { label: 'Checkout (modal)' } }); ``` 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](/docs/api#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](/docs/concepts#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 *Figure: A component gets a proxy from useMachine(). The proxy calls the real actor and registers in the registry. The overlay selects a preview in the registry, and the proxy reads it.* **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.