# 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.