pmndrs/jotai
github.com/pmndrs/jotai ↗ · 326 files · 1.0 MB
visit jotai.org or npm i jotai Jotai scales from a simple useState replacement to an enterprise TypeScript application.
Overview
Jotai is a TypeScript state-management library for React applications, with a separate vanilla store API usable outside React. Atoms describe primitive, computed, or writable state; each store owns their values and tracks dependencies to propagate changes to subscribers. This pinned v3.0.1 checkout also contains persistence and async utilities, Vite examples, a Gatsby documentation website, regression tests, and package-release workflows.
System map
The repository separates the vanilla dependency engine from its React adapter and utility modules. The published artifact is an ESM library, while the website and examples are separate applications with their own dependencies. Storage is in memory unless a utility connects an atom to an external adapter. Build and release behavior is defined by package scripts and GitHub Actions.
- src/index.ts re-exports the vanilla and React APIs; separate barrels expose atom/store primitives and Provider/hooks, including the v3 raw-value hooks.
- package.json defines seven library entrypoints, publishes only dist, declares sideEffects:false, and provides TypeScript declarations only for >=5.5; React >=18 is an optional peer.
- atom() creates configuration objects with read/write functions and optional init values; createStore() delegates to INTERNAL_buildStoreRev4 unless overridden.
- buildStore owns per-store weak maps for atom state, mounting, and invalidation, sets for changes and lifecycle callbacks, and a store epoch holder; its public surface is get/set/sub.
- Provider supplies either an explicit store or a lazily created store retained in useRef; useStore selects options.store, then context, then the module's default store.
- The root build emits src into dist through tsc --noCheck; type checking is a separate test:types script. Compilation uses strict NodeNext modules and an ES2020 target.
- The Gatsby website sources ../docs as MDX, indexes documents through Algolia, and has Vercel function configuration for api/*.js; the Hacker News example independently uses Vite and React.
- Publishing runs on published GitHub releases and builds before pnpm publish; preview releases build and invoke pkg-pr-new with example templates. The pnpm workspace contains the root and website.
Feature catalog
The primary user surface is a composable state API rather than an application router or CLI. Primitive and derived atoms support synchronous values, async computations, and custom write actions. Utilities add persistence, state transformations, stream integration, and hydration. The examples and documentation website demonstrate these capabilities and provide search, theme selection, and support inquiries.
- atom overloads support primitive state, read-only derived state, writable derived state, and initial-value atoms with custom writes; primitive writes accept values or updater functions.
- useAtom combines reading and setting; useAtomValue resolves promise values with Suspense, while useAtomValueRaw and useAtomValueRawSync return promise values without consuming them.
- Users can isolate state with Provider, access stores outside React through get/set/sub, hydrate atom arguments once per store unless forced, and run imperative get/set callbacks through useAtomCallback.
- State-control utilities include RESET-aware atoms, computed defaults that can be overwritten and restored, Redux-style reducers, zero-argument refresh, and lazy initial-value factories.
- selectAtom retains the previous slice when equalityFn matches; splitAtom exposes per-item atoms and remove/insert/move actions for writable arrays; freezeAtom wraps reads and self-writes with recursive freezing.
- atomWithStorage supports sync or async adapters, RESET deletion, optional eager initialization, and external subscriptions. atomWithObservable supports streams and subject writes; unwrap exposes fallback values while promises are pending.
- Examples offer editable uppercase text and character counts, async Hacker News item browsing, animated todo filtering and deletion, explicit todo save/load, and nested form/field editing through optics and splitAtom.
- The website provides a tabbed introduction/API overview, slug-based MDX documentation, Algolia search with section hits, a persisted dark-mode toggle, and a professional-support inquiry form.
Data flow
Atom objects identify state, while stores own values, dependency epochs, and subscriptions. Reads establish dependencies and reuse cached results when their validity checks succeed. Writes propagate through custom atom actions, invalidate affected state, recompute dependencies, and notify subscribers. Promise, storage, documentation-indexing, and contact adapters introduce distinct external boundaries.
- An initial primitive value enters atom.init; the first store read creates AtomState and initializes its value through the self-getter. The same atom configuration can therefore have separate state in separate stores.
- readAtomState reuses initialized state when a mounted atom is not invalidated or its validation epoch equals the store epoch; otherwise it recursively compares recorded dependency epochs before recomputing.
- A derived read's getter records dependency atom epochs, removes those atoms from the stale-dependency set, and registers pending dependents for promises; stale dependencies are pruned synchronously or when the read promise settles.
- writeAtomState supplies a getter and setter to atom.write; self-writes update initialized state, advance the store epoch when the atom epoch changes, and invalidate dependents, while writes to other atoms recurse through their write functions.
- Changed mounted or pending dependents are traversed for topological recomputation; flushCallbacks deduplicates listeners and lifecycle callbacks, drains newly generated work, and aggregates callback errors.
- React's ordinary raw hook reads store.get into reducer state and subscribes in an effect; Object.is suppresses unchanged reducer values. Async values pass through createContinuablePromise, whose abort handler follows replacement promises before useAtomValue consumes them.
- atomWithStorage reads on mount and optionally at construction, feeds subscription updates into baseAtom, and writes memory before storage.setItem/removeItem. createJSONStorage translates values through JSON and filters browser storage events by storage area and key.
- Website MDX metadata/body become Algolia document and heading records, then search queries refine the Docs index and hits navigate to /docs/{slug}. Support form data separately becomes a JSON POST and a Postmark text email with the submitted address as ReplyTo.
Behavior traces
The source walkthrough followed React startup and subscription, a concrete text-edit action, and storage initialization/write/reset end to end. Additional traces followed async Hacker News loading and website search/support behavior. The steps below describe execution order and relevant branches from source inspection. They are not runtime observations.
- Startup: the starter calls createRoot(...).render(<StrictMode><App/>); Counter calls useAtom(countAtom), useStore falls back to getDefaultStore, and createStore builds the store on first use.
- Initial subscription: useAtomValueRaw initializes from store.get, then its effect invokes subscribe; store.sub mounts dependencies before the atom, adds the listener, recomputes, and flushes. createState then compares the rendered value against store.get and requests a rerender if changed or errored.
- Text edit: Input.onChange sends e.target.value through useSetAtom to store.set; defaultWrite self-sets textAtom, writeAtomState invalidates dependents, and recomputation evaluates length/uppercase reads before subscribed components reread.
- Cleanup: the raw hook's effect returns the store subscription cleanup; it removes the listener, unmounts atoms only when no listener or mounted dependent still requires them, then recomputes and flushes queued onUnmount callbacks.
- Persistence: atomWithStorage constructs baseAtom from initialValue unless getOnInit requests storage; mounting reloads and subscribes. A normal write computes the next value, updates baseAtom, and calls setItem; a promise write waits for resolution; RESET restores initialValue and calls removeItem.
- Async browsing: Next increments postId; postData reads that ID, fetches the Firebase item endpoint, and returns response.json(). PostTitle reads the promise through useAtomValue and renders under Suspense; replacement promises trigger abort handlers, although this example does not pass a signal to fetch.
- Documentation search: SearchModal reads searchAtom, mounts InstantSearch on Docs, CustomSearchBox updates local query state and throttles refine by 200 ms, Boundary hides empty queries or reports zero hits, and Hit navigation closes the modal.
- Support inquiry: handleSubmit rejects a filled client honeypot or previously completed submission, marks the form submitted, and POSTs JSON to /api/contact; the handler rejects missing fields, awaits sendEmail, and returns 200 or 500. Only a 200 response sets hasReceived and clears fields.
Testing signals
Tests and CI were inspected, not executed; no passing result or coverage percentage is asserted. Vitest runs the library suites in jsdom with React Testing Library and source aliases. Inspected regressions cover dependency notifications, cancellation, persistence, raw hooks, and garbage collection. Root automation checks several compatibility dimensions, but its configured scope does not establish end-to-end website or service coverage.
- Vitest selects tests under tests, uses jsdom and the React plugin, enables globals for Testing Library cleanup, aliases jotai imports to src, and loads jest-dom matchers.
- Store regressions assert unchanged-value notification suppression, dependency cleanup, and recovery of derived notifications during nested no-op writes plus subscription churn and synchronous event cascades (#3353).
- Async tests use fake timers and assert abort on dependency replacement, continued execution after unsubscribe, Suspense loading states, and suppression of obsolete results during rapid updates.
- Storage tests assert mount hydration, persisted increments, RESET deletion, getOnInit reads, sync/async validator fallbacks, and custom subscription delivery; these exercise adapters and jsdom rather than live cross-tab browsers.
- Raw-hook tests assert stable promise identity and preservation of a subscription across value changes; RawSync tests assert non-suspending promise returns and detection of a child's mount-time write.
- Memory-leak tests use jest-leak-detector for unreferenced atoms, subscribed/unsubscribed state, and removed sync/async dependencies; separate store tests expect deep synchronous graphs to surface stack overflow and listeners to continue after another listener throws.
- Inspected CI runs format/types/lint/spec/build across Node 22.12, 24, and 26; separate matrices test React 18/19 plus canary/experimental versions, TypeScript 5.5–5.9, and built ESM in development/production modes.
- Configured coverage includes src/** and defines no threshold; ordinary root type checking includes src/tests/benchmarks, while lint excludes examples and website. The inspected root test workflow does not invoke website builds, contact-service checks, or example UI tests.
Risk map
These are source observations and explicitly identified hypotheses, not confirmed vulnerabilities. The core's main correctness risks involve dependency/lifecycle ordering, deep reads, and pending promise retention. External trust boundaries appear in storage, example network content, and website contact handling. Several documentation and dependency mismatches require care when using ancillary applications to validate the root library.
- AtomState.p strongly retains pending dependents; the source explicitly notes possible memory leaks, and removal occurs when the associated promise settles. Hypothesis: never-settling promises can prolong retention beyond the ordinary weak-map lifecycle. (inferred)
- Graph reads and mounting recurse even though invalidation/recomputation use iterative traversal; a regression explicitly expects sufficiently deep reads/subscriptions to overflow. Reads that mutate the store receive a development warning rather than enforced rejection.
- Storage JSON parsing accepts any valid JSON shape. withStorageValidator wraps getItem but copies subscribe unchanged, and atomWithStorage updates memory before persistence; validation of external subscription values and rollback after storage failures are not implemented in these functions.
- Both contact handlers check only truthiness of name/email/message before sending email; their bodies contain no method restriction, authentication, rate-limit, size, or email-format checks. The form's honeypot is client-only and is not included in its POST body; deployment-level controls were not verified.
- Support.handleSubmit sets hasSubmitted before fetch, has no catch/reset branch, and handles only status 200. Its overlay displays Sending... whenever submission started but hasReceived remains false, including the visible non-200 path.
- The Hacker News example casts response.json() to PostData without runtime validation or response.ok handling, passes external text to html-react-parser, and uses external url values directly in links. These are content-validation boundaries; exploitability was not tested.
- The root is v3.0.1, but the website declares jotai ^2.4.1 and the atomFamily example ^2.10.4; that example imports atomFamily from jotai/utils even though v3 documentation moves it to jotai-family. These surfaces do not directly validate the root v3 implementation.
- The useAtomValueRaw documentation says render-to-subscription changes are missed, whereas createState now rereads immediately after store.sub and invokes the callback when changed. Separately, website SSR theme bootstrap catches storage reads but leaves JSON.parse and its initialization write outside that catch.
Extension points
Atoms and store adapters are the principal composition interfaces. Public utilities accept application-supplied selectors, equality functions, storage implementations, observables, and callbacks. Internal store hooks and replaceable building blocks offer deeper instrumentation but explicitly carry compatibility warnings. Website documentation extends through MDX content and a shared component map.
- New state abstractions can be implemented as atom(read, write): read receives dependency get and an AbortSignal option, while write receives get/set plus arbitrary typed arguments and can return an application-defined result.
- Writable atoms support onMount(setAtom) returning cleanup; INTERNAL_onInit receives the store on first reference. The latter is explicitly internal and unstable.
- createStore provides independently owned state, Provider accepts an existing store, and INTERNAL_overrideCreateStore receives the previous override to replace store construction.
- SyncStorage/AsyncStorage define getItem/setItem/removeItem plus optional subscribe; createJSONStorage accepts string-storage factories and JSON reviver/replacer functions, enabling sessionStorage or custom async backends.
- selectAtom accepts selector and equality callbacks, splitAtom accepts a keyExtractor, and unwrap accepts a fallback using the previously resolved value; memoization depends on these function/object identities.
- atomWithObservable accepts a dependency-aware getObservable factory and subscribable or Symbol.observable-style sources; subject-like sources additionally expose writes through next(data). useAtomCallback adapts arbitrary get/set callbacks to a memoized write-only atom.
- INTERNAL_buildStoreRev4 merges Partial<BuildingBlocks> into defaults, freezes the block table, and exports keyed accessors; experimental store hooks provide creation/read/change/mount/unmount/flush listeners. Internal consumers are told to pin versions.
- Adding MDX under docs feeds Gatsby's filesystem source and slug-based page template; frontmatter.nav controls navigation sorting, while gatsby-shared.js maps MDX elements and embedded demo components to website renderers.
Contributor handoff
This brief is grounded in the pinned checkout, including more than twelve source files and multiple end-to-end source traces. Tests and CI were inspected, not executed, and the investigation did not install, build, benchmark, contact services, or modify files. Future edits should preserve the vanilla/React boundary and verify the specific affected regression suites. Ancillary v2 applications, unstable internals, and documentation drift need explicit consideration.
- Begin core work with atom.ts, store.ts, and the relevant internals building blocks; atom configuration identity and per-store state ownership are separate concerns. Preserve referentially stable atoms when used from React render functions.
- For notification edits, preserve recompute-before-flush behavior in storeSet, storeSub, and unsubscribe; read the #3353 tests before changing the changedAtoms-size optimization or introducing nested notification behavior.
- For hook edits, read both raw subscription implementations and continuablePromise; the ordinary raw hook includes a post-subscription value check, while RawSync uses useSyncExternalStore. Reconcile mount-timing documentation against these sources.
- For storage changes, preserve getOnInit versus onMount loading, promise-update resolution, RESET deletion, and storage-area/key filtering; inspect the adapter tests rather than assuming browser persistence is infallible.
- When execution is authorized, use the existing test:spec script for the smallest affected Vitest suite and test:types for API changes, then applicable lint/format checks. This investigation inspected those tests and CI declarations but did not execute them or establish passing status.
- Keep ESM .js import suffixes, strict/exact optional types, isolated declarations, and seven exported entrypoints consistent; build uses --noCheck, so emitted output alone is insufficient type validation.
- Treat website/example validation separately from root tests: workspace membership is root plus website, inspected applications declare v2 dependencies, and root lint excludes them. benchmarks/run-all.ts shells out to npx tsx and its header describes generated JSON/chart artifacts; it is not a read-only inspection command.
- Contribution guidance requests failing tests for core fixes, focused changes, conventional commit types, and discussion-first submission rather than direct contributor PRs. INTERNAL exports warn of changes without notice; none of these instructions authorize writes or releases during this read-only task.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 117 | 69% |
| Markdown | 84 | docs/config |
| JavaScript | 52 | 31% |
| JSON | 21 | docs/config |
| CSS | 14 | docs/config |
| HTML | 13 | docs/config |
| YAML | 12 | docs/config |
Start reading here
Probable source entrypoint: src/index.ts — inferred from the directory tree and manifest, not the upstream docs.
Source roots
src/ (33 files)
Source layout — src/
| Path | Files |
|---|---|
src/react/ | 12 |
src/vanilla/ | 17 |
src/index.ts | 1 |
src/react.ts | 1 |
src/utils.ts | 1 |
src/vanilla.ts | 1 |
Repository structure
| Top-level path | Files |
|---|---|
docs/ | 72 |
examples/ | 71 |
website/ | 68 |
tests/ | 46 |
src/ | 33 |
.github/ | 13 |
benchmarks/ | 10 |
img/ | 1 |
Docs found: CONTRIBUTING.mdREADME.md
Package
package.json — jotai v3.0.1, 32 declared dependencies.
@eslint/js@testing-library/dom@testing-library/jest-dom@testing-library/react@types/node@types/react@types/react-dom@vitejs/plugin-react@vitest/coverage-v8@vitest/eslint-plugin@vitest/uibenny
CI & config entrypoints
README.md— Repository readmesrc/index.ts— TS entrypointexamples/todos_with_atomFamily/vite.config.ts— Vite configexamples/todos_with_atomFamily/src/App.tsx— React rootexamples/text_length/vite.config.ts— Vite configexamples/text_length/src/App.tsx— React rootexamples/hacker_news/vite.config.ts— Vite configexamples/hacker_news/src/App.tsx— React rootexamples/starter/vite.config.ts— Vite configexamples/mega-form/vite.config.ts— Vite config
Structural health signals
Average score 9.1/10 across 96 analyzed source files; 1 hotspot surfaced.
src/vanilla/internals.ts— 1322 lines, score 6.4 (Large file, Deep nesting)website/src/pages/index.js— 375 lines, score 6.7 (Deep nesting, Long function/block)website/gatsby-node.js— 264 lines, score 6.7 (Deep nesting, Long function/block)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
6abd0ae3365e2026-09-29 — v3.0.15ea9573b5ff92026-09-29 — chore(deps): update dev dependencies (#3374)85aa951942dc2026-09-29 — fix #3371 (#3373)0c23f15ab8952026-09-29 — fix(vanilla): export store type (#3370)5a613709773f2026-09-29 — docs: clarify fork branch contribution flow (#3372)