Open-source project
pmndrs/jotai avatar
pmndrs/jotai

Jotai: atoms as objects, write-only atoms, and a type map that changes at TypeScript 5.5

👻 Primitive and flexible state management for React

21,318 stars729 forksTypeScriptMIT

At a glance

What is it?
Jotai replaces a store of named slices with plain atom objects, each one holding an initial value and optional read and write functions, so a component reads state the same way it calls useState. The cost is that identity, write access, and the TypeScript resolution path are all decided at the atom declaration, and the front page never mentions the v3 major release.
Who is it for?
Jotai fits a React codebase that wants per-component state without a store, provider chain, or string-keyed actions, and whose team is comfortable treating an atom object as the unit of ownership. It does not fit a project that needs a named, discoverable state tree, a debugging surface over a single store, or a migration story that the repository itself explains.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 6 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • pmndrs/jotai21,318 ★ · +43
Star history
Repository2026-09-212026-11-15
pmndrs/jotai21.3k21.3k

43 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Atoms are identified by the object, never by a string key

The first examples are all module-level declarations:

jsx
import { atom } from 'jotai'

const countAtom = atom(0)
const countryAtom = atom('Japan')
const citiesAtom = atom(['Tokyo', 'Kyoto', 'Osaka'])
const mangaAtom = atom({ 'Dragon Ball': 1984, 'One Piece': 1997, Naruto: 1999 })

The values can be primitives, arrays, or objects, and there is no naming step, no key registry, and no provider that declares state up front. That is the difference the project draws against Recoil, where state is looked up by string key. It buys type safety, since the value type flows out of the declaration, and it costs discoverability: nothing in a running app enumerates which atoms exist, so a state inventory has to come from reading the source. The examples folder in this repository includes a starter project and a todos_with_atomFamily project, which is the shape of the answer when you need atoms created from a parameter rather than declared by hand.

Whether an atom can be written is decided by which arguments you pass

A derived atom is created by passing a read function, and get returns the current value of any atom:

jsx
const doubledCountAtom = atom((get) => get(countAtom) * 2)

Add a second argument and it becomes writable:

jsx
const decrementCountAtom = atom(
  (get) => get(countAtom),
  (get, set, _arg) => set(countAtom, get(countAtom) - 1)
)

Omit the read function entirely, passing null in its place, and you get an action atom that holds nothing and only performs writes:

jsx
const multiplyCountAtom = atom(null, (get, set, by) =>
  set(countAtom, get(countAtom) * by),
)

The consequence for a component is direct. useAtom returns a value and a setter, and whether that setter does anything is decided at the declaration site, not at the call site. A read-only derived atom read by a component that tries to write gives the user an interface backed by nothing, so the read and write signature is where the state contract actually lives.

An async read function turns a fetch into part of the atom graph

The read function can be asynchronous, which is how data loading is expressed here:

jsx
const urlAtom = atom('https://json.host.com')
const fetchUrlAtom = atom(async (get) => {
  const response = await fetch(get(urlAtom))
  return await response.json()
})

Because the read depends on urlAtom through get, changing the url atom and letting the function conclude is what re-renders the consumer; the component itself holds no effect and no fetch call. The heading for this pattern points at React's Suspense reference, which is the honest signal about the contract: the value arrives after the first render rather than with it, so the consuming component has to be prepared for a pending read. The tradeoff is that caching and staleness are no longer something a component decides, since the atom read is the only place the request exists.

Async writes return nothing, so the caller cannot wait on them

The write function can be async as well, and the example shows the intended shape:

jsx
const fetchCountAtom = atom(
  (get) => get(countAtom),
  async (_get, set, url) => {
    const response = await fetch(url)
    set(countAtom, (await response.json()).count)
  }
)

In the example, the component calls compute from a click handler without awaiting it, and the value it renders comes from the read half. So the button looks idle for the duration of the request, and the update lands only when set runs. Two things follow for anyone building on this: there is no per-call error path exposed to the component unless you write one, and a second click before the first finishes races with the first set. Decide whether that belongs in the atom or in the component before you copy the pattern into a form.

TypeScript 5.5 is a hard gate in the exports map

package.json splits every entry point on a version condition. For TypeScript 5.5 and above, the exports field resolves to the real declarations, and typesVersions maps any release at or above 5.5 to dist/*. For anything older, both the exports types condition and typesVersions point at a single file, dist/ts_version_5.5_and_above_is_required.d.ts, which exists only to carry the requirement. The consequence shows up as an editor experience rather than a runtime error: on TypeScript 4.x the package imports, the JavaScript runs, and every symbol resolves to one declaration that tells you to upgrade. Check the compiler version before blaming the atom definitions, since the same code will type fine on a teammate's machine and look empty on yours.

Seven export paths, one shipped folder, and no declared side effects

The published surface is mapped entry by entry: the root, ./utils, ./vanilla, ./vanilla/utils, ./vanilla/internals, ./react, and ./react/utils, each with its own types and default build, plus ./package.json itself. files is set to dist and nothing else, sideEffects is false, and type is module with main pointing at dist/index.js. Two practical effects. sideEffects false is what lets a bundler drop an import whose only purpose was a module side effect, so an atom file must not depend on that import running. And the split between the root entry and ./react tells you the core is usable without React bindings, with vanilla/internals named as an internals path rather than as a stability promise.

The 2kb core leaves the rest to separate packages

The size claim is specific: a minimal core API of 2kb, alongside many utilities and extensions. The front page demonstrates the core and nothing beyond it, so selectors, atom families, devtools, and persistence are outside what you get from the documented API and belong to the utilities and extensions layer. Part of that layer ships in the same package, through the ./utils and ./react/utils export paths. The repository layout follows the same split, with src/, tests/, docs/, examples/, benchmarks/, and a website/ folder, and pnpm workspace files rather than a single package build.

The front page is a tutorial and stays silent on the v3 release

Everything the repository front page gives you is a short tutorial: create primitives, read with useAtom, derive with get, add a write function, go async, then a note that atoms are monads with a link to the functional programming write-up on jotai.org. There is no API reference, no migration section, and no mention that v3.0.0 shipped on 2026-09-08 with v3.0.1 following on 2026-09-29. So the front page cannot answer what changed, and a team moving from 2.x has to look outside it for the breaking changes. The rest of the material points outward too, to the documentation site, a course, and the runnable example projects under examples/, including hello, todos, mega-form, text_length, and hacker_news.

Editorial conclusion

Jotai fits a React codebase that wants per-component state without a store, provider chain, or string-keyed actions, and whose team is comfortable treating an atom object as the unit of ownership. It does not fit a project that needs a named, discoverable state tree, a debugging surface over a single store, or a migration story that the repository itself explains. Before upgrading past 2.x, find the v3 notes, since v3.0.0 shipped on 2026-09-08 and the front page does not mention the change, and check your TypeScript version against the 5.5 gate in the package exports before you expect editor types to work. Decide early whether async atoms and a write-only action atom match your data flow, since both move work out of the component. The last push landed on 2026-10-23.

Frequently asked questions

what is jotai atom

An atom is a piece of state created with atom() and an initial value, which can be a string, number, array, or object. Derived atoms add a read function that uses get, and a second argument can add a write function that uses set, or a null first argument produces a write-only action atom.

how to install jotai

The install is npm i jotai, and the documentation site is jotai.org. The package is version 3.0.1, is published as an ES module, and its types resolve properly only on TypeScript 5.5 or above.

Is Jotai better than Redux?

The project does not make that comparison, and it names only one difference: no string keys, in contrast to Recoil. What it claims about itself is a minimal 2kb core API, many utilities and extensions, and the ability to scale from a useState replacement to an enterprise TypeScript application.

What is the difference between Jotai and Zustand?

Nothing in this repository compares Jotai with Zustand, so the comparison has to come from elsewhere. What Jotai itself states is that its unit of state is an atom object created with atom() and read in components through useAtom, with derived values expressed as read functions.

what does jotai mean in japanese

The repository never defines the word, in Japanese or in any other language. Its description of itself is a primitive and flexible state management library for React, and the front page never explains the name.

Official sources

  1. License: MIT
  2. pmndrs/jotai on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/pmndrs-jotai.svg)](https://hysenlabs.com/projects/pmndrs-jotai)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/pmndrs-jotai.svg)](https://hysenlabs.com/projects/pmndrs-jotai)

Was this useful?