# Jotai DevTools

<!-- ::platform-badge platform="both" -->

Inspect named Jotai atoms, their current values, and recorded changes. Register the atoms you need with the same store your app uses, then follow a value through the event history and diff views.

<!-- ::tool-film id="jotai" -->

<!-- ::jotai-live-demo -->

## Installation

<!-- ::PM npm="npm install @buoy-gg/jotai" yarn="yarn add @buoy-gg/jotai" pnpm="pnpm add @buoy-gg/jotai" bun="bun add @buoy-gg/jotai" -->

---

## Setup

Call `watchAtoms` once at module scope — pass your Jotai store and a named map of your atoms. No wrappers, no middleware, no modifications to existing atoms.

```tsx
import { getDefaultStore } from 'jotai';
import { watchAtoms } from '@buoy-gg/jotai';
import { countAtom } from './atoms/count';
import { authAtom } from './atoms/auth';
import { cartAtom } from './atoms/cart';

watchAtoms(getDefaultStore(), {
  countAtom,
  authAtom,
  cartAtom,
});
```

That's it. Registered atoms automatically appear in the Jotai tool inside your FloatingDevTools menu.

Change a registered atom through your app, then confirm its new value and event appear. If it is absent, check that `watchAtoms` received the same store as your provider.

---

## Atoms Tab

Browse all registered atoms and their **live current value**:

- **Atom Name** — Color-coded for easy identification across both tabs
- **Value Type** — `number`, `boolean`, `object`, `array · N`, `null`, etc. at a glance
- **Live Value** — Tap any atom to expand and see the full value tree, updated in real-time
- **Change Count** — How many times this atom has changed this session
- **View History** — Jump straight to the filtered event history for a single atom

The Free row cap is used after the filter.

---

## Events Tab

Every atom change is captured with rich metadata:

- **Atom Name** — Which atom changed, color-coded for quick identification
- **Value Transition** — `prev → next` at a glance (e.g. `0 → 5`, `null → {name, email}`, `[2 items] → [3 items]`)
- **Category Badge** — `INIT` (initial registration) or `WRITE` (subsequent update)
- **No Change** — Flags writes that fired but didn't actually change the value
- **Timestamp** — When the change occurred with relative time

---

## Detail View

Tap any event to see three detailed tabs:

### Change Tab
Atom name, timestamp, category badge, and a diff summary showing which object keys changed.

### Value Tab
The full atom value after this change — collapsible JSON tree for objects, raw value for primitives.

### Diff Tab
Side-by-side comparison of before and after — additions (green), removals (red), modifications (yellow). Choose between tree view or split view.

---

## Using a Custom Store

If your app uses a `<Provider>` with a custom store, pass it directly:

```tsx
import { createStore, Provider } from 'jotai';
import { watchAtoms } from '@buoy-gg/jotai';
import { countAtom, authAtom } from './atoms';

const myStore = createStore();

watchAtoms(myStore, { countAtom, authAtom });

export function App() {
  return (
    <Provider store={myStore}>
      <YourApp />
    </Provider>
  );
}
```

---

## Features

### Atom Color Coding
Each atom gets a consistent color across the Atoms tab, Events tab, and detail views. Colors are assigned automatically based on atom name and persist for the session.

### Value Transition at a Glance
Every event row shows `prev → next` so you immediately know what changed — no need to tap in for simple updates.

### Atom History
Tap "view history" on any atom in the Atoms tab to see all events scoped to just that atom — useful for tracking a specific piece of state through a flow.

### Search & Filter
Find events by atom name or value content. Add filter patterns to hide noisy atoms from both the Atoms and Events tabs simultaneously.

### Copy to Clipboard
Export the full atoms snapshot or event history as JSON for bug reports, test fixtures, or sharing with teammates (Pro).

### Recording Toggle
Pause atom capture when you need to focus, resume when ready.

---

## What It Can't Do

Only registered atoms are visible. Jotai has stores, but Buoy does not automatically discover every atom your app may use.

Read-only atoms cannot be written. A derived atom can be writable if it defines a write function; derivation alone does not determine whether a write is allowed. Check the tool's reported capability before editing or restoring it.

## What's Next

- [Zustand DevTools](./zustand) — Zustand store monitor with state diffing and jump-to-state
- [Redux DevTools](./redux) — Redux action monitor with state diffing and time-travel
- [React Query DevTools](./react-query) — TanStack Query inspection
- [Network Monitor](./network) — Inspect supported HTTP requests

---

## FAQ

### How do I inspect Jotai atoms in React Native?

Install `@buoy-gg/jotai` and register your atoms — they appear in the on-device browser with live values, write history, and diffs.

## Web support

Register the app’s atoms and store with watchAtoms. The shared panel and snapshot provider use those registrations. Import it from the package's `/web` entry (7.0.41 or later). See [Web installation](../web/installation#tool-setup) for registration, dependencies, and browser boundaries.