Jotai DevTools

🚀 Features

• Debug 🐞 atom values with ease
• ⏳ Time-travel through your atoms and find bugs faster than before
• Out-of-the-box 🔌 support for async/suspendable atoms
• Built-in Dark mode 🌗
• ✅ Supports custom store
• ✅ Works with provider-less mode
• ✅ Works with Next.js
• ✅ Supports custom nonce for CSP
• ✅ Hides private atoms with ability to configure
• ✅ Parses all the JavaScript values with JSON Tree view
• ✅ Diff checking with additions and deletion highlights

📺 Preview

☝️ Prerequisites

• Jotai version >=v2.12.3
• React version >=17.0.0

📦 Setup

(See complete setup guide for UI-based devtools below)

1# yarn
2yarn add jotai-devtools
3
4# npm
5npm install jotai-devtools --save

✨ UI DevTools

Enhance your development experience with the UI based Jotai DevTool

Babel plugin setup - (Optional but highly recommended)

Use Jotai babel plugins for optimal debugging experience. Find the complete guide on jotai.org

Eg.

1{
2  "plugins": [
3    // Enables hot reload for atoms
4    "jotai/babel/plugin-react-refresh",
5    // Automatically adds debug labels to the atoms
6    "jotai/babel/plugin-debug-label"
7  ]
8}

Next JS setup

You may skip this section if you're not using Next.js.

Enable transpilePackages for the UI CSS and components to be transpiled correctly.

1// next.config.ts
2
3const nextConfig = {
4  // Learn more here - https://nextjs.org/docs/advanced-features/compiler#module-transpilation
5  // Required for font css to be imported correctly 👇
6  transpilePackages: ['jotai-devtools'],
7};
8
9module.exports = nextConfig;

Available props

1type DevToolsProps = {
2  // Defaults to false
3  isInitialOpen?: boolean;
4  // pass a custom store
5  store?: Store;
6  // Defaults to light
7  theme?: 'dark' | 'light';
8  // Defaults to 'bottom-left'
9  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
10  // Custom nonce to allowlist jotai-devtools specific inline styles via CSP
11  nonce?: string;
12  // We recommend keeping these options static. i.e. set it only once. Avoid connecting it to re-renderable state
13  options?: {
14    // Private atoms are used internally in atoms like `atomWithStorage` or `atomWithLocation`, etc. to manage state.
15    // Defaults to `false`
16    shouldShowPrivateAtoms?: boolean;
17    // Expands the JSON tree view on initial render on Atom Viewer tab, Timeline tab, etc.
18    // Defaults to `false`
19    shouldExpandJsonTreeViewInitially?: boolean;
20    // The interval (in milliseconds) between each step of the time travel playback.
21    // Defaults to `750ms`
22    timeTravelPlaybackInterval?: number;
23    // The maximum number of snapshots to keep in the history.
24    // The higher the number the more memory it will consume.
25    // Defaults to `Infinity`. Recommended: `~30`
26    snapshotHistoryLimit?: number;
27  };
28};

Provider-less

1import { DevTools } from './JotaiDevTools';
2import 'jotai-devtools/styles.css';
3const App = () => {
4  return (
5    <>
6      <DevTools />
7      {/* your app */}
8    </>
9  );
10};

With Provider

1import { createStore } from 'jotai';
2
3import { DevTools } from 'jotai-devtools';
4import 'jotai-devtools/styles.css';
5
6const customStore = createStore();
7
8const App = () => {
9  return (
10    <Provider store={customStore}>
11      <DevTools store={customStore} />
12      {/* your app */}
13    </Provider>
14  );
15};

Tree-shaking

Jotai DevTools is currently only available in development mode. We're changing this in the future to allow it to be used in production as well.

Therefore, we recommend wrapping the DevTools in a conditional statement and tree-shake it out in production to avoid any accidental usage in production.

Vite

1import { DevTools } from 'jotai-devtools';
2import css from 'jotai-devtools/styles.css?inline';
3
4const JotaiDevTools = () =>
5  process.env.NODE_ENV !== 'production' ? (
6    <>
7      <style>{css}</style>
8      <DevTools />
9    </>
10  ) : null;
11
12const App = () => {
13  return (
14    <>
15      <JotaiDevTools />
16      {/* your app */}
17    </>
18  );
19};

NextJS

Create a DevTools.tsx file in your project and export the DevTools component.

1import 'jotai-devtools/styles.css';
2export { DevTools } from 'jotai-devtools';

Then, in your app, import the DevTools component conditionally.

1import dynamic from "next/dynamic";
2import type { ComponentType } from "react";
3import type { DevToolsProps } from "jotai-devtools";
4
5let DevTools: ComponentType<DevToolsProps> | null = null;
6
7if (process.env.NODE_ENV !== "production") {
8  DevTools = dynamic(
9    () => import("./DevTools").then((mod) => ({ default: mod.DevTools })),
10    { ssr: false }
11  );
12}
13
14const App = () => {
15  return (
16    <>
17      {DevTools && <DevTools />}
18      {/* your app */}
19    </>
20  );

Hooks

Detailed documentation is available on https://jotai.org/docs/api/devtools

1import {
2  useAtomsSnapshot,
3  useGotoAtomsSnapshot,
4  useAtomsDebugValue,
5  // Redux devtool hooks
6  useAtomDevtools,
7  useAtomsDevtools,
8} from 'jotai-devtools';

Migration guides

Migrate ƒrom @emotion/react to native CSS

With the latest release, Jotai DevTools no longer depends on @emotion/react and is replaced it with native CSS.

1. Remove @emotion/react from your dependencies

   1# yarn
   2yarn remove @emotion/react
   3
   4# npm
   5npm uninstall @emotion/react

2. Replace @emotion/react with jotai-devtools/styles.css in your code

Note that this css file may get included in your production builds please import it conditionally if you want to avoid that.

1import { DevTools } from 'jotai-devtools';
2+ import 'jotai-devtools/styles.css';

Migrate Jotai to V2

Find the official migration guide on jotai.org

Migrate jotai/react/devtools to jotai-devtools

1. Install this package

   1# npm
   2npm install jotai-devtools --save
   3
   4# yarn
   5yarn add jotai-devtools

2. Update imports from jotai/react/devtools to jotai-devtools

   1import {
   2 useAtomsSnapshot,
   3 useGotoAtomsSnapshot,
   4 useAtomsDebugValue,
   5 // Redux devtool integration hooks
   6 useAtomDevtools,
   7 useAtomsDevtools,
   8- } from 'jotai/react/devtools';
   9+ } from 'jotai-devtools';

Inspirations

Redux DevTools React Query DevTools

Other announcements

✨ First announcement