Skip to content

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 kotick

kotick/reducer needs only React. Your app does not need xstate or @xstate/react.

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:

PackageVersionsNeeded for
react, react-dom18 or 19Both adapters
xstate5.28 or laterkotick/xstate only
@xstate/react6.1 or laterkotick/xstate only

Quick start

  1. Mount the overlay once, near the root of the app. Both adapters use the same overlay:

  2. Connect your machines through the adapter:

    Declare the reducer as a machine with defineReducerMachine. Then call useMachineReducer instead of useReducer:

    From a switch reducer shows how to change a reducer into a machine.

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.

  1. Get the shadow root:

    If shadow is undefined, <Kotick /> is not mounted, or the page is from a production build.

  2. Open the panel:

  3. 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_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 examples. Without the check, the build makes a fixtures chunk that the app never loads.