Installation
kotick has an adapter for each kind of machine. kotick/reducer is for useReducer machines, and kotick/xstate is for XState v5 machines. Neither is the default. Select the adapter that your app uses:
pnpm add kotickkotick/reducer needs only React. Your app does not need xstate or @xstate/react.
The command also installs xstate and @xstate/react, because kotick does not install them. If your app already has them, install only kotick. An app can use both adapters, and this command installs all that both need.
Add kotick to dependencies, not to devDependencies. Your app code imports kotick/reducer or kotick/xstate, thus the production build needs the package.
Requirements
kotick uses the versions of these packages that your app has:
| Package | Versions | Needed for |
|---|---|---|
react, react-dom | 18 or 19 | Both adapters |
xstate | 5.28 or later | kotick/xstate only |
@xstate/react | 6.1 or later | kotick/xstate only |
Quick start
-
Mount the overlay once, near the root of the app. Both adapters use the same overlay:
-
Connect your machines through the adapter:
Declare the reducer as a machine with
defineReducerMachine. Then calluseMachineReducerinstead ofuseReducer:From a switch reducer shows how to change a reducer into a machine.
Import the XState hooks from
kotick/xstateinstead of@xstate/react:The hooks have the same names and signatures as in
@xstate/react. Actors that you create outside React need one more step, withconnect(). Refer to XState for that step, and for a lint rule that finds the imports from@xstate/react.
Start the dev server and click the bubble in the bottom-right corner, or press Alt+S. The panel lists each machine that runs on the page. Select a machine to see its states. Select a state to preview it, and select it again to release it.
Check the install
You can check the install without a screen, for example in a browser test or from an agent. In development, <Kotick /> adds a <div data-kotick-root> to document.body, or to portalTarget. The overlay is in the open shadow root of this element.
-
Get the shadow root:
If
shadowisundefined,<Kotick />is not mounted, or the page is from a production build. -
Open the panel:
-
After the panel renders, read the machine ids:
The result is a list such as
['checkout']. If a machine is not in the list, refer to the FAQ.
The panel keeps its open state and its page from the last visit. Thus, in a browser that used the panel before, step 2 can close the panel, or open the page of one machine. To start with a closed panel, reset the panel before step 1.
kotick writes nothing to the console when it starts. A message that starts with [kotick] tells you about a problem. Refer to Troubleshooting.
Before you release
You do not have to remove <Kotick /> or change the imports before a release. In a production build, <Kotick /> renders nothing, and the bundler removes the registry and the panel. Refer to Choose an adapter for what each adapter keeps, and for its size.
Check two things in your build:
- The bundler must replace
process.env.NODE_ENVwith"production". Vite, Next.js (webpack and Turbopack) and React Router do this. With esbuild, add--define:process.env.NODE_ENV='"production"'. - The fixtures loader must have a development check, as in the Fixtures examples. Without the check, the build makes a fixtures chunk that the app never loads.