GO — Healthy across the board

• Last commit 2w ago
• 14 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 50% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against dependency CVEs from deps.dev and OpenSSF Scorecard}

Jotai is a primitive and flexible state management library for React that enables fine-grained reactivity without string keys (unlike Recoil). It provides a minimal 2kb core with atoms as basic state units, derived atoms for computed values, and seamless integration with async data, side effects, and TypeScript. The library scales from simple useState replacements to complex enterprise applications with features like scope isolation, immer integration, and hooks-based APIs. Monorepo structure: the main source is organized around src/ (inferred from large TypeScript footprint) with separate examples and benchmarks/ directories. Extensions live in docs/extensions/ (immer, query, redux, relay, tRPC, urql, valtio, etc.) suggesting modular plugin architecture. Benchmarks include atom-creation.ts, computed-read.ts, diamond.ts, subscription.ts, and wide-fan-out.ts, indicating careful performance profiling for subscription and derived-atom evaluation patterns.

React developers building anything from simple component state to large-scale applications who want lightweight, type-safe state management without the boilerplate of Redux or the string-key overhead of Recoil. Contributors are typically library users who extend Jotai with integrations (urql, tRPC, Relay, Valtio) or contribute core performance improvements.

Production-ready and actively maintained. The project shows strong signs of maturity: a comprehensive test suite (CI workflows: test.yml, test-multiple-builds.yml, test-multiple-versions.yml), 543kb of TypeScript source code across a well-organized structure, and an established GitHub Actions pipeline including compressed-size tracking and ecosystem compatibility tests. The 2+ year track record with semantic versioning (v2.10.4 evident in package examples) and active Discord community (see README badge) indicate sustained adoption.

Low risk overall, but monitor: the core maintainers are from the Poimandres collective (verified by Discord link in README), so there is some single-maintainer risk for critical bugs. The project's reliance on careful state subscription logic means behavioral regressions can be subtle (hence the compressed-size.yml, ecosystem-ci.yml, and test-multiple-versions.yml workflows to catch them). No major red flags in dependency footprint, but the extensive utilities ecosystem (extensions/ folder) means ecosystem plugins may lag behind core releases.

Active development with recent workflow additions (ecosystem-ci.yml, test-multiple-versions.yml) suggesting focus on compatibility and performance regressions. The preview-release.yml workflow indicates pre-release testing pipeline in place. Focus areas based on file structure: TypeScript coverage improvements (test-old-typescript.yml), bundle size optimization (compressed-size.yml), and broad framework/library ecosystem testing (ecosystem-ci.yml for tRPC, urql, Relay, etc.).

git clone https://github.com/pmndrs/jotai.git
cd jotai
npm install
npm run test
npm run build

For examples (e.g., the hacker_news example in package.json snippet):

cd examples/hacker_news
npm install
npm run dev

Daily commands:

npm install
npm run test          # run test suite
npm run build         # build distribution
npm run dev           # start dev server (if example)

For the example in the Dependencies snippet:

cd examples/hacker_news
npm run dev           # starts Vite dev server on typically localhost:5173

• package.json — Defines Jotai's core identity as a state management library with minimal dependencies and build configuration.
• README.md — Establishes the project's mission: primitive, flexible, and lightweight state management for React.
• docs/core/atom.mdx — Documents the fundamental atom concept that all Jotai usage builds upon.
• docs/core/use-atom.mdx — Explains the primary hook API for subscribing to and updating atom state in React components.
• docs/guides/core-internals.mdx — Details the internal subscription and update mechanisms that make Jotai's reactivity work.
• babel.config.mjs — Configures transpilation and optimization of Jotai's core abstractions for production builds.

• Atom (JavaScript objects, optional read/write functions) — Defines a unit of state with optional read, write, and initialization logic.
  • Failure mode: Invalid atom definition (missing value config) causes runtime errors.
• Provider (React Context, Provider component) — Wraps React components to provide scoped, isolated atom storage via React context.
  • Failure mode: Missing Provider for explicit store usage causes atoms to use global default store.
• useAtom hook (React Hooks API) — Subscribes functional component to atom state and returns [value, setter] tuple.
  • Failure mode: Called outside Provider or during SSR without explicit store can cause hydration mismatches.
• Derived atoms (Atom read/write functions, lazy evaluation) — Computed atoms that depend on other atoms and are evaluated on-demand.
  • Failure mode: Circular atom dependencies cause infinite loops or stale value caches.
• Store (default or custom) (WeakMap for atom storage, Set for subscribers) — Holds in-memory atom state and manages subscriptions across the app.
  • Failure mode: Memory leaks if subscribers are not cleaned up (rare with React integration).

• React Component → useAtom hook — Component calls hook with atom reference to subscribe to and mutate state.
• useAtom hook → Provider Store — Hook reads current atom value from store and registers component as subscriber.
• Provider Store → Atom — Store evaluates atom's read function (if derived) or returns cached primitive value.
• Component setter → Atom write function — Component calls setter, triggering atom's write function (or direct value update for primitives).
• Atom write → Dependent atoms — Updated atom invalidates derived atoms that depend on it; triggers re-evaluation.
• Store subscription → React Component — Subscribers are notified of atom changes; components re-render with new value.

Add a New Documentation Recipe

1. Create a new .mdx file following existing recipe structure with headings, code examples, and explanation. (docs/recipes/[your-recipe-name].mdx)
2. Follow the naming and format conventions established in sibling recipe files like atom-with-toggle.mdx. (docs/recipes/)

Add a New Extension Guide

1. Create a new .mdx file documenting integration with external libraries (e.g., immer, valtio, xstate). (docs/extensions/[library-name].mdx)
2. Include motivation, installation, usage examples, and trade-offs compared to alternatives. (docs/extensions/)

Add a Performance Benchmark

1. Create a new TypeScript file in benchmarks/ following the pattern of existing benchmarks (atom-creation.ts, subscription.ts). (benchmarks/[scenario-name].ts)
2. Register the benchmark in run-all.ts to execute it in the test suite. (benchmarks/run-all.ts)

• React Hooks (useAtom, etc.) — Provides ergonomic subscription and state mutation API that integrates seamlessly with functional components.
• Atom-based model (similar to Recoil) — Enables fine-grained reactivity, code splitting, and composition without boilerplate.
• Provider pattern with Store — Isolates atom state scope and enables testing, SSR, and multi-instance scenarios.
• TypeScript — Type-safe state definition and inference for atom values and derivations.

• Primitive atoms over class-based models

  • Why: Reduces cognitive overhead and enables functional composition patterns.
  • Consequence: Users must understand functional dependency graphs; more mental modeling than imperative APIs.

• Optional Provider (uses default store if not provided)

  • Why: Reduces boilerplate for simple apps and tutorials.
  • Consequence: Can lead to confusion in SSR or multi-instance scenarios where explicit scope is needed.

• Lazy atom evaluation (read computed only when accessed)

  • Why: Prevents unnecessary derived atom recalculations and enables code splitting.
  • Consequence: Debugging data flow can be harder; values are computed on-demand rather than proactively.

• Does not provide built-in time-travel debugging (see devtools extension as separate package).
• Does not enforce immutability at runtime; relies on user discipline and optional Immer integration.
• Not a real-time sync engine; async atoms require explicit API calls, not bi-directional binding.
• Does not handle form state directly; recipes and extensions provide that pattern separately.

• Avg cyclomatic complexity: ~5 — Core Jotai is a lightweight subscription system; complexity lies in derived atom chains and SSR integration, not in individual function logic.
• Largest file: docs/guides/core-internals.mdx (350 lines)
• Estimated quality issues: ~2 — Well-maintained project with TypeScript, comprehensive tests, and minimal linting issues; main gotchas are documentation edge cases (SSR, circular deps) rather than code smell.

• Global atom state without explicit Provider (High) — docs/guides/core-internals.mdx, docs/core/provider.mdx: Using atoms without wrapping in <Provider> causes all instances to share a single global store, making multi-instance or SSR scenarios error-prone.
• Creating atoms inside components (High) — docs/guides/composing-atoms.mdx: Defining atoms within render scope creates new atom instances on each render, breaking identity and memoization.
• Circular atom dependencies (High) — docs/guides/composing-atoms.mdx: Atom A depending on B while B depends on A causes infinite loops or stale computations.
• Unstructured derived atoms without memoization (Medium) — docs/guides/performance.mdx: Creating new derived atoms with inline read functions on every render wastes computation and breaks caching.

• Atom subscription graph (Store implementation) (Computational (O(n) with dependency depth)) — Deep derived atom chains require traversing and invalidating multiple dependent atoms on each state change.
• useAtom hook re-render notification (Rendering (avoidable with selectAtom or comparison functions)) — Components subscribed to an atom re-render even if derived values are unchanged; requires manual equality checks or useMemo.
• SSR hydration with atoms (Integration (see docs/guides/nextjs.mdx for patterns)) — Atoms initialized on server must be manually synced to client store to prevent hydration mismatches.

No required env vars or external services for core development. However: (1) TypeScript version sensitivity—test-old-typescript.yml suggests older TS versions may have issues; (2) React version constraints—test-multiple-versions.yml tests against multiple React versions, so ensure you understand which React features you're using; (3) Atom identity matters—atoms are compared by reference, not value, so passing { key: 'count' } twice creates two atoms; (4) SSR gotchas—useAtom must run in browser context; the Provider scope is crucial for server-side rendering to avoid hydration mismatches.

• Atom (primitive reactive unit) — Atoms are the fundamental building block of Jotai; understanding their identity, read/write functions, and lazy evaluation is essential to avoid common pitfalls like unintended re-renders or stale closures
• Fine-grained reactivity — Jotai uses subscription-based updates (evidenced by benchmarks like diamond.ts and wide-fan-out.ts) to ensure only components reading specific atoms re-render, not the entire tree
• Derived atoms (read function closures) — Computed atoms use read functions that capture dependencies via get() calls; they enable lazy evaluation and memoization, critical for performance in complex dependency graphs
• Provider scope isolation — The Provider component creates an isolated store instance; understanding scope is crucial for multi-page apps, SSR, and testing to avoid state leakage between contexts
• Async atoms and suspense boundaries — Jotai seamlessly integrates async read functions and Promise handling, making it easy to manage data fetching; docs/extensions/query.mdx and integration tests show patterns
• Diamond dependency problem — Multiple atoms deriving from the same source (diamond pattern in benchmarks/diamond.ts) must update consistently; Jotai's subscription model ensures this without redundant evaluations
• Bundle size optimization via tree-shaking — Jotai's 2kb claim (tracked by compressed-size.yml) depends on ES modules and dead-code elimination; only imported utilities add to bundle, making it critical for library composition

• reduxjs/redux — Predecessor approach to state management; Jotai's no-string-keys design is an explicit improvement over Redux's action/reducer boilerplate
• facebookexperimental/Recoil — Direct competitor using atoms for fine-grained reactivity; Jotai's main differentiator is no string keys and simpler API
• pmndrs/valtio — Sister library in Poimandres ecosystem for proxy-based state; docs/extensions/valtio.mdx shows how to bridge Valtio state into Jotai atoms
• pmndrs/zustand — Sibling Poimandres store library offering simpler, hook-based state; some projects use both Zustand and Jotai for different scopes
• tannerlinsley/react-query — Server-state management paired with Jotai for client state; docs/extensions/query.mdx demonstrates integration pattern

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for async atom patterns in docs/guides/async.mdx

The async guide exists but there are no dedicated test files validating the async patterns documented (suspense, promise handling, error boundaries). A new test suite would ensure examples in docs/guides/async.mdx remain accurate and catch regressions in async behavior across Jotai versions.

• [ ] Create src/tests/async-atoms.test.ts covering suspense atoms, promise atoms, and error handling patterns
• [ ] Add tests for the specific examples shown in docs/guides/async.mdx
• [ ] Validate behavior with useTransition and Suspense boundaries from React 18
• [ ] Integrate into test.yml workflow to run on all PRs

Add TypeScript strict mode tests for docs/guides/typescript.mdx examples

TypeScript guide exists but there's no test-old-typescript.yml coverage for strict mode checking. The repo has test-old-typescript.yml workflow but lacks validation that TypeScript examples in the guide work with strictNullChecks, strictFunctionTypes, and other strict flags enabled.

• [ ] Create src/tests/typescript-strict.test.ts with generics and type inference examples from docs/guides/typescript.mdx
• [ ] Add a tsconfig.strict.json with all strict flags enabled
• [ ] Create new GitHub Action workflow test-typescript-strict.yml that validates these patterns
• [ ] Ensure atom generic typing, derive patterns, and store usage examples all pass strict checks

Add ecosystem integration tests for React Native patterns referenced in docs/guides/react-native.mdx

React Native guide exists in docs but there are no specific tests validating that Jotai atoms work correctly in React Native environments. The ecosystem-ci.yml workflow exists for other integrations but lacks React Native validation, risking silent breakages in RN projects.

• [ ] Create src/tests/react-native.test.ts with mocked React Native environment testing store persistence, hooks without DOM APIs
• [ ] Add tests for AsyncStorage persistence patterns mentioned in the guide
• [ ] Create new GitHub Action test-react-native.yml that runs these tests in a simulated RN environment
• [ ] Validate that core atoms and useAtom hooks work without browser globals (localStorage, requestAnimationFrame)

• Add integration test for selectAtom() utility with derived atoms to docs/extensions/—currently no dedicated .mdx exists despite selectAtom being mentioned in benchmarks
• Write performance regression test for the 'wide-fan-out.ts' benchmark in CI (fan-out scenario with 100+ subscribers to one atom)—benchmark exists but is not gated in workflows
• Expand docs/core/provider.mdx with explicit examples of scope isolation and multi-provider setup; currently CONTRIBUTING.md and provider.mdx lack concrete multi-scope examples

The Jotai project has a moderate security posture with some concerns. The primary risk is the use of html-react-parser without visible sanitization mechanisms, which could lead to XSS vulnerabilities if parsing untrusted HTML. Loose dependency version constraints increase the attack surface through transitive dependencies. The codebase lacks visible security header configuration and environment variable validation. Strengths include use of modern frameworks (React 18, Vite 6, TypeScript 5) and the .gitignore file properly configured. Recommendations focus on tightening dependency management, implementing input sanitization for HTML parsing, and adding security headers configuration.

• High · Potential XSS Vulnerability with html-react-parser — package.json - dependencies: html-react-parser. The dependency 'html-react-parser' (^1.2.6) is used for parsing HTML content. This library can be vulnerable to XSS attacks if user-supplied HTML is parsed without proper sanitization. The caret (^) version constraint allows automatic updates that may introduce security issues. Fix: 1) Use a more recent version with security patches. 2) Implement input validation and sanitization before passing HTML to the parser. 3) Consider using alternatives like DOMPurify in combination with html-react-parser. 4) Use exact version pinning instead of caret ranges for security-critical dependencies.
• Medium · Loose Dependency Version Constraints — package.json - dependencies section. Multiple dependencies use caret (^) version ranges, allowing automatic minor and patch updates. This can introduce breaking changes or security vulnerabilities without explicit review. Affected packages: @react-spring/web, html-react-parser, jotai, react, react-dom. Fix: Implement stricter versioning by using exact versions (remove ^ prefix) for production dependencies, or at minimum use tilde (~) constraints. Use lock files (package-lock.json or yarn.lock) and review dependency updates through automated security scanning tools.
• Medium · Missing Security Headers Configuration — Vite configuration (not provided in analysis). No security headers configuration visible in Vite configuration or build scripts (vite.config.js/ts not shown). This could lead to missing security headers like Content-Security-Policy, X-Frame-Options, X-Content-Type-Options when deployed. Fix: Configure security headers in vite.config.ts including: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Strict-Transport-Security. Use middleware or server configuration to enforce these headers.
• Low · No HTTPS/TLS Configuration Visible — package.json - scripts section. Development configuration uses 'vite' and 'vite preview' without explicit HTTPS enforcement. No visible HTTPS configuration in the provided files. Fix: In development, enable HTTPS with: vite --https. For production, ensure deployment enforces HTTPS and uses valid SSL/TLS certificates. Add HSTS headers.
• Low · Missing Environment Variable Validation — Project root - missing .env.example or documentation. No .env file handling or environment variable validation pattern visible. Application may be vulnerable to misconfiguration if sensitive data is accidentally exposed through environment variables. Fix: Create a .env.example file documenting required environment variables. Implement runtime validation of environment variables. Add .env to .gitignore (appears to be done) and document secure configuration practices.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/pmndrs/jotai shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live pmndrs/jotai repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/pmndrs/jotai.

What it runs against: a local clone of pmndrs/jotai — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in pmndrs/jotai | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 46 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of pmndrs/jotai. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/pmndrs/jotai.git
#   cd jotai
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of pmndrs/jotai and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "pmndrs/jotai(\\.git)?\\b" \\
  && ok "origin remote is pmndrs/jotai" \\
  || miss "origin remote is not pmndrs/jotai (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "docs/core/atom.mdx" \\
  && ok "docs/core/atom.mdx" \\
  || miss "missing critical file: docs/core/atom.mdx"
test -f "docs/core/use-atom.mdx" \\
  && ok "docs/core/use-atom.mdx" \\
  || miss "missing critical file: docs/core/use-atom.mdx"
test -f "docs/guides/core-internals.mdx" \\
  && ok "docs/guides/core-internals.mdx" \\
  || miss "missing critical file: docs/guides/core-internals.mdx"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 46 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~16d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/pmndrs/jotai"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.