jotai-devtools

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)

# yarn
yarn add jotai-devtools

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

{
  "plugins": [
    // Enables hot reload for atoms
    "jotai/babel/plugin-react-refresh",
    // Automatically adds debug labels to the atoms
    "jotai/babel/plugin-debug-label"
  ]
}

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.

// next.config.ts

const nextConfig = {
  // Learn more here - https://nextjs.org/docs/advanced-features/compiler#module-transpilation
  // Required for font css to be imported correctly 👇
  transpilePackages: ['jotai-devtools'],
};

module.exports = nextConfig;

Available props

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

Provider-less

import { DevTools } from './JotaiDevTools';
import 'jotai-devtools/styles.css';
const App = () => {
  return (
    <>
      <DevTools />
      {/* your app */}
    </>
  );
};

With Provider

import { createStore } from 'jotai';

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

const customStore = createStore();

const App = () => {
  return (
    <Provider store={customStore}>
      <DevTools store={customStore} />
      {/* your app */}
    </Provider>
  );
};

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

import { DevTools } from 'jotai-devtools';
import css from 'jotai-devtools/styles.css?inline';

const JotaiDevTools = () =>
  process.env.NODE_ENV !== 'production' ? (
    <>
      <style>{css}</style>
      <DevTools />
    </>
  ) : null;

const App = () => {
  return (
    <>
      <JotaiDevTools />
      {/* your app */}
    </>
  );
};

NextJS

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

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

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

import dynamic from "next/dynamic";
import type { ComponentType } from "react";
import type { DevToolsProps } from "jotai-devtools";

let DevTools: ComponentType<DevToolsProps> | null = null;

if (process.env.NODE_ENV !== "production") {
  DevTools = dynamic(
    () => import("./DevTools").then((mod) => ({ default: mod.DevTools })),
    { ssr: false }
  );
}

const App = () => {
  return (
    <>
      {DevTools && <DevTools />}
      {/* your app */}
    </>
  );

Hooks

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

import {
  useAtomsSnapshot,
  useGotoAtomsSnapshot,
  useAtomsDebugValue,
  // Redux devtool hooks
  useAtomDevtools,
  useAtomsDevtools,
} 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.

• Remove @emotion/react from your dependencies

  # yarn
  yarn remove @emotion/react
  
  # npm
  npm uninstall @emotion/react
  

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

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

Migrate Jotai to V2

Find the official migration guide on jotai.org

Migrate jotai/react/devtools to jotai-devtools

• Install this package

  # npm
  npm install jotai-devtools --save
  
  # yarn
  yarn add jotai-devtools
  

• Update imports from jotai/react/devtools to jotai-devtools

  import {
   useAtomsSnapshot,
   useGotoAtomsSnapshot,
   useAtomsDebugValue,
   // Redux devtool integration hooks
   useAtomDevtools,
   useAtomsDevtools,
  - } from 'jotai/react/devtools';
  + } from 'jotai-devtools';
  

Inspirations

Redux DevTools React Query DevTools

Other announcements

✨ First announcement

Changelog

0.12.0 (2025-04-27)

• fix: re-add dev only export + add warning + docs around tree shaking (#186) (9835e66), closes #186
• chore: update dependencies (#185) (9982bf2), closes #185
• refactor: drop support for dev_* methods (#180) (2ab02e2), closes #180