# Installation
Install the package, mount the overlay, and connect your machines through kotick/reducer or kotick/xstate.
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:
With `kotick/reducer`:
```bash
pnpm add kotick
```
Other package managers: `npm install kotick`, `yarn add kotick`, `bun add kotick`.
`kotick/reducer` needs only React. Your app does not need `xstate` or `@xstate/react`.
With `kotick/xstate`:
```bash
pnpm add kotick xstate @xstate/react
```
Other package managers: `npm install kotick xstate @xstate/react`, `yarn add kotick xstate @xstate/react`, `bun add kotick xstate @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
1. Mount the overlay once, near the root of the app. Both adapters use the same overlay:
```tsx
import { Kotick } from 'kotick';
export function App() {
return (
<>
>
);
}
```
2. Connect your machines through the adapter:
With `kotick/reducer`:
Declare the reducer as a machine with `defineReducerMachine`. Then call `useMachineReducer` instead of `useReducer`:
```diff
- const [state, dispatch] = useReducer(reducer, { status: 'idle' });
+ const [state, dispatch] = useMachineReducer(searchMachine, { status: 'idle' });
```
[From a switch reducer](/docs/reducer#from-a-switch-reducer) shows how to change a reducer into a machine.
With `kotick/xstate`:
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';
```
The hooks have the same names and signatures as in `@xstate/react`. Actors that you create outside React need one more step, with `connect()`. Refer to [XState](/docs/xstate#actors-outside-react) 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` (`⌥S` on macOS). 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, `` adds a `
` to `document.body`, or to `portalTarget`. The overlay is in the open shadow root of this element.
1. Get the shadow root:
```js
const shadow = document.querySelector('[data-kotick-root]')?.shadowRoot;
```
If `shadow` is `undefined`, `` is not mounted, or the page is from a production build.
2. Open the panel:
```js
shadow.querySelector('button[aria-label^="Kotick"]').click();
```
3. After the panel renders, read the machine ids:
```js
[...shadow.querySelectorAll('[data-machine]')].map((row) => row.getAttribute('data-machine'));
```
The result is a list such as `['checkout']`. If a machine is not in the list, refer to the [FAQ](/docs/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](/docs/troubleshooting#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](/docs/troubleshooting#console-warnings).
## Before you release
You do not have to remove `` or change the imports before a release. In a production build, `` renders nothing, and the bundler removes the registry and the panel. Refer to [Choose an adapter](/docs/concepts#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_ENV` with `"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](/docs/fixtures) examples. Without the check, the build makes a fixtures chunk that the app never loads.