How pmndrs/jotai works
Project type and purpose
• Jotai is an open-source, zero-boilerplate state-management library for React (and vanilla JS).
• It provides a minimal core, React bindings, vanilla JS APIs, Babel plugins, utilities, and extensive documentation + examples.
File structure
• src/
– core engine entry (src/index.ts)
– react integration (src/react/…)
– vanilla API (src/vanilla/…)
– Babel tooling (src/babel/…)
– shared utilities (src/utils.ts, src/types.d.ts)
• docs/ & website/
– docs/*.mdx → documentation site content
– website/ → Gatsby-based site source + API endpoints
• examples/
– multiple standalone demos (each a Vite/React project consuming the library)
• build & CI
– rollup.config.mjs → bundling to npm artifacts
– babel.config.js → for tests & compiled output
– GitHub Actions workflows → test, lint, publish pipelines
• tests/
– vitest config + test suites for core, react, vanilla, and babel plugins
Extract architecture hints from the README
• Core API is atom-based, functional, asynchronous/derived, monadic
• Extensions include async atoms, computed atoms, write-only atoms
• React components use hooks (useAtom, useAtomValue, useSetAtom) that wrap core atoms
• Encourages composability and interoperability (vanilla & React)
a. Core Library Module
• Atom creation & state storage engine
• Derived/async utilities
b. React Integration Layer
• Hooks (useAtom, etc.)
• Provider component
c. Vanilla Integration Layer
• Direct atom APIs (atom, read/write, utils)
d. Tooling & Build Pipeline
• Babel plugins & preset (debug labels, HMR)
• Rollup bundler → npm packages (cjs, esm)
• GitHub Actions → test, build, publish
e. Documentation & Website
• Markdown/MDX content → Gatsby → Deployed to Vercel
• API routes (contact form)
f. Examples & Demos
• Standalone React/Vite projects consuming published package
g. External Services
• npm registry (package publish)
• GitHub (source repo, CI)
• Vercel/Netlify (website hosting)
• CodeSandbox / StackBlitz (live demos)
Relationships & data flows
• React layer → React app components (useAtom hooks)
• Build pipeline: src → Babel → Rollup → npm artifacts
• CI → triggers tests on src, examples, website → on success publishes to npm & deploys website
• Examples/website → import from npm or local package link
• External tooling (CodeSandbox) → live code embeds
Architectural patterns & design principles
• Modular, layered architecture: core engine decoupled from framework bindings
• Functional programming / monads: atoms as composable state units
• Separation of concerns:
– Core logic (state management)
– Presentation bindings (React hooks)
– Tooling (build & HMR)
– Documentation (MDX + static site)
• Extensibility via utilities and extensions (cache, optics, reducers, etc.)