Skill
This page is a skill in the Agent Skills format. It tells a coding agent how to set up kotick, change a reducer into a machine, write fixtures, and fix the console warnings.
To use it with Claude Code, select Copy skill, and save the text as .claude/skills/kotick/SKILL.md in your project. Other agents that support Agent Skills read skills from a folder of their own. Refer to the docs of your agent.
kotick is a development overlay for React 18 and 19. It lists each state machine on the page and all of its states, and shows any state in the running app. The package has three entries:
| Entry | Exports |
|---|---|
kotick | <Kotick />, the overlay. Mount it once. |
kotick/reducer | defineReducerMachine, useMachineReducer and defineFixtures, for useReducer machines. It needs only React. |
kotick/xstate | The hooks of @xstate/react with the same names and signatures, connect and defineFixtures, for XState v5 machines. |
Neither adapter is the default, and an app can use both. In a production build, <Kotick /> renders nothing, and the bundler removes the registry and the panel. Do not remove <Kotick /> or change imports before a release.
Use only the API in this file. Do not guess the API of kotick from XState or other libraries. The examples import from src through the @/ alias. Use the import style of the project.
Select the adapter
- If the app uses
xstate5.28 or later with@xstate/react6.1 or later, usekotick/xstate. - If a component keeps a union of states in
useReducer, with one key that holds the name of the state, usekotick/reducer. - XState v4, Zustand, Redux and other state libraries do not work. kotick needs a machine that declares its states.
- If the app has no machine, tell the user, and offer to declare one
useReducerflow as a reducer machine.
Set up
-
Install
kotickwith the package manager of the project. Put it independencies, notdevDependencies, because the production build imports the adapters. Forkotick/xstate, also installxstateand@xstate/reactif the app does not have them. -
Mount
<Kotick />once, in a component that stays mounted when the page changes. In a Vite or other single-page app, put it in the root component, after the routes. In Next.js, do the steps in Next.js. -
Connect the machines, as the next two sections show.
-
Do the steps in Verify.
Connect XState machines
-
Change each import from
@xstate/reacttokotick/xstate. Search the source for@xstate/reactto find all of them. A component that keeps the old import works, but the panel does not list its machine. -
Wrap each actor that the app creates outside React with
connect(). Use the actor thatconnect()returns everywhere in the app, for example inuseSelector(sessionActor, …). -
Give each machine an
idin its definition. Without one, kotick makes an id from the states and the context keys, and that id changes when they change. -
Add this rule to the ESLint or Oxlint config of the project, so that new imports from
@xstate/reactfail:
The hooks and createActorContext take one more option, debug, and connect() takes the same object as its second argument. debug: { label } names an instance in the panel. debug: { id } replaces the machine id. debug: { disabled: true } keeps the actor out of kotick.
Convert a useReducer reducer
A switch reducer has one branch for each event. A machine has one handler for each state and event.
- Make the state a union with one key that holds the name of the state. That key is the
discriminant. - For each branch of the
switch, write a handler under each state in which the event is valid. Leave it out of the other states, and they ignore the event. - Move each
useEffectthat depends on the name of the state to theeffectof that state. Changedispatchtosend, and read props and hook values throughinput(). - Change
useReducer(reducer, initial)touseMachineReducer(machine, initial). - Keep the tests of the old reducer, and run them on
machine.reducer.
defineReducerMachine has two calls. The first call takes the type arguments: the union of states, the union of events, and the type of the input that the effects read. The second call takes the definition. This machine of a search box starts the request in the effect of loading:
The component calls useMachineReducer, which returns [state, dispatch] as useReducer does. When the machine declares an input type, the hook requires input:
Obey these rules:
stateshas one entry for each state name, and no other key. The discriminant has a string literal value in each member of the union.- A handler gets
(state, event)and returns the next state. It is pure, and it gets no input. A state ignores each event that it does not list, and a handler that returnsstateignores its event. - An
effectgets(state, send, input), and can return a cleanup. It starts after the commit that enters its state. Its cleanup runs after the commit that leaves the state, and when the component unmounts. After the cleanup,senddoes nothing. StrictMode starts the effect, runs its cleanup, and starts it again, so cancel a request in the cleanup, as theloadingeffect above does withAbortController. input()returns the newest input that the component gave the hook. A new input does not restart an effect.- Send the result of async work with
sendfrom aneffect. Do notawaitin an event handler and thendispatchthe result, and do notdispatchit from a componentuseEffect. During a preview, kotick blocksdispatchand does not replay the events, so the machine stays in the loading state. - Call
useMachineReducerin place ofuseReducer. Do not givemachine.reducertouseReducer. Then no effect runs, and the panel does not list the component. - Call
useMachineReduceronly in client components. Server code can import the machine file and callmachine.reducer.
Write fixtures
A fixture gives data to a state that the app did not go to yet, such as an error. Without a recording or a fixture, a reducer machine cannot preview the state, and an XState machine uses the live context and logs a warning.
Put the fixture sets in a file of their own. With kotick/reducer, each key is a state name, and each value is a whole state object whose discriminant is that key. The keys are optional. satisfies CompleteFixtures<typeof machine> requires a fixture for each state:
With kotick/xstate, each key is a leaf id, the dot path to a state without child states, such as payment.error. Each value is { context }, with the full context type of the machine:
Give <Kotick /> a loader with a development check, so that production builds do not have the fixtures. Put the loader in a const at module scope. A function made during render is new on each render, and kotick calls it again each time.
That check is for Vite. In Next.js and other bundlers, use process.env.NODE_ENV !== 'production'. Do not use process.env in Vite, because a default Vite app does not have the Node.js types.
A file with sets for both adapters imports one defineFixtures under another name, for example import { defineFixtures as defineReducerFixtures } from 'kotick/reducer'. In the panel, Copy context copies the shown state as JSON. For a reducer machine, the JSON is a fixture. For an XState machine, it is the value of context.
Next.js
kotick and kotick/xstate start with 'use client'. kotick/reducer has no directive, so a server component or a route handler can import a machine file and call machine.reducer.
In the App Router, render the overlay in the root layout, after {children}. A server component cannot give a function to a client component, so render <Kotick fixtures={…} /> in a client component:
Call useMachineReducer, the hooks of kotick/xstate and createActorContext() only in client components. In the Pages Router, render <Kotick /> in pages/_app.tsx. On the server, kotick does nothing, and the overlay mounts after hydration.
Verify
-
Run the type check of the project. It checks the machine definitions, the
inputof the hook, and the keys and values of the fixtures. -
If you can control a browser, open the app in development, and run this in the page. The result is the list of machine ids, such as
['search']. Each machine must be in it.If
shadowisundefined,<Kotick />is not mounted, or the page is from a production build. The panel keeps its open state inlocalStorageunderkotick:ui, so the click can close it. To start with a closed panel, remove that key and reload the page. -
Read the browser console. kotick writes nothing when it works. Each message that starts with
[kotick]tells you about a problem.
| Message starts with | Fix |
|---|---|
A machine has no id | Add an id to the machine, or set debug: { id } on the hook or on connect(). |
connect() was given an actor that a hook already registers | Remove the connect() call, and set debug on the hook. |
No recorded or fixture context for | Go to the state one time in the app, or write a fixture for it. |
Can't preview "…" on "…": it has no recorded or fixture context | Go to the state one time in the app, or write a fixture for it. |
Fixtures for "…" name "…", which isn't a leaf state | Use leaf ids, such as payment.error. |
The fixture of "…" on "…" isn't in the "…" state | Give each fixture the discriminant of its key. |
"…" has no state "…", so the set leaves its fixture out | Use the state names of the machine as keys. |
"…" is in "…", which its definition doesn't declare | Add the state to states, or correct the handler or the initial state. |
The fixtures loader failed | Correct the error that follows the message. |
Expected fixtures to be an array | Export an array from the fixtures file: export default [defineFixtures(…)]. |
Dropped an event without a string type | Send events as objects, such as send({ type: 'SUBMIT' }). |
Two versions of kotick are on this page | Install one version. npm ls kotick finds the package that brings in the other one. |
Other messages, such as Can't preview or Can't follow | Reload the page. If the message shows again, tell the user to report it. |
If a machine is not in the panel, examine these causes:
<Kotick />is not mounted.- A component imports the hook from
@xstate/react. - An actor from
createActor()does not go throughconnect(). - A component gives
machine.reducertouseReducer. - The instance has
debug: { disabled: true }.
Tests
Test runners set NODE_ENV to test, so kotick works in tests as in development. Without a preview, the hooks behave as without kotick, so the tests do not have to change. To turn the overlay off, mock kotick in the setup file. For kotick/xstate, also mock it as this Vitest example shows:
Do not mock kotick/reducer, because its hook runs the transitions and effects of the app. To test the transitions of a reducer machine, call machine.reducer(state, event) with no React. A state that does not list the event returns the same object, so toBe(state) checks that the state ignores the event.
Props of the overlay
All props of <Kotick /> are optional.
| Prop | Type | Default | Use |
|---|---|---|---|
position | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'bottom-right' | The corner of the bubble and the panel. |
defaultOpen | boolean | false | Opens the panel on the first visit. |
shortcut | string | false | 'alt+s' | The keys that open and close the panel, such as ctrl+shift+d. false turns it off. |
fixtures | FixtureSet[] or a loader | None | The fixture sets, or a function that imports them. |
portalTarget | Element | ShadowRoot | document.body | The element that gets the overlay. Use document.documentElement when body has a transform, a filter or contain. |
Limits of a preview
- The real machine continues to run. When the user releases a preview, the app shows the real state at that time.
- Events that the UI sends during a preview go to the event log of the panel, not to the machine.
- The machine effects of the previewed state do not run. For XState, these are invoked actors, delayed transitions and entry actions. For a reducer machine, this is the
effectof the state. Component effects that react to the state do run. - Child actors of an XState machine are listed under their parent, but they cannot be previewed. History states cannot be selected.
- kotick checks only the name of a reducer state. A recording from before you added a field to a state does not have that field.