jotai

Jotai

Overview

Use Jotai v3 as the baseline for new code. For existing projects, inspect the installed Jotai and extension versions before giving version-sensitive advice. Preserve the requested behavior, architecture, and dependency choices; use refactoring guidance only where it serves the task.

Workflow

• Identify state ownership, the store used by each reader and writer, atom identity, async behavior, and relevant tests before changing code.
• Choose the smallest change that satisfies the request. Derive computed values, separate independently updated state when useful, and use named action atoms when commands benefit from a shared update path.
• Verify the behavior at the appropriate level: vanilla store tests for state logic and isolation, component tests for subscriptions and user interactions. Match the existing test setup when practical.

Core Invariants

• Atom configs identify state by reference; values belong to a store. Keep atom configs stable across renders and use the same store for all participants in a state flow.
• Replace object and array values immutably. Jotai uses Object.is to detect value changes; mutating a value and setting the same reference can suppress updates.
• Read-function get tracks dependencies; write-function get reads without establishing a reactive subscription. Keep reads free of unrelated side effects.
• Use useAtomValue for reads, useSetAtom for writes, and useAtom for both. Use vanilla get/set/sub for imperative integrations; a read alone does not mount an atom.
• Keep initialization and subscription lifetimes explicit. onMount follows atom subscriptions, not module loading or setter calls. Isolate request-owned state on the server.
• Prefer plain atom composition before utilities. Add utilities or extensions when they encode the required semantics more clearly, checking compatibility with the installed major version.

Reference Routing

Read only the files that match the task:

• references/atom-modeling.md for deciding atom boundaries, derived atoms, action atoms, writable adapters, resets, storage, and family-style parameterized atoms.
• references/react-usage.md for hook selection, Provider/store scope, vanilla integrations, SSR, hydration, dynamic atom creation, and component architecture.
• references/async-and-side-effects.md for Suspense, async reads, async actions, abort signals, non-Suspense states, refresh flows, and external side effects.
• references/performance-and-large-state.md for render tuning, selectAtom, focusAtom, splitAtom, large objects, lists, and dependency graph depth.
• references/typescript-and-testing.md for TypeScript inference, writable atom argument types, ExtractAtomValue, and testing strategy.
• references/utilities-decision-guide.md for choosing built-in utilities such as storage, SSR hydration, resettable/default atoms, lazy atoms, callbacks, reducers, select, split, and family migration.
• references/extensions-decision-guide.md for choosing extension packages such as TanStack Query, optics, Immer, effects, location, scope, cache, XState, GraphQL/RPC, and external-store bridges.
• references/tools-and-debugging.md for choosing Devtools, Babel, SWC, and Rolldown support for debugging, labels, React Refresh, and bundler integration.
• references/recipes-decision-guide.md for deciding when to use or adapt official recipes such as debounce, listeners, broadcast, compare, toggle, custom hooks, reducer hooks, and atom effects.
• references/version-migration.md for migrating from v2 to v3: raised React/TypeScript/Node requirements, ESM-only packaging, removed APIs and their replacements, and changes to jotai/vanilla/internals.

Compatibility And Source Verification

This revision was written against Jotai 3.0.1, and covers Jotai 2.20.x where the two differ. Before giving version-sensitive API guidance, determine the target project's installed Jotai and extension-package versions, then inspect their exported types, source, or matching documentation and tests. Do not assume current documentation matches the installed version.