React Atom

The React adapter for @mongez/atom. Every atom carries React hooks (useValue, useState, use(key), useWatch) and a Provider component as instance methods — no useAtomValue / useSetAtom split, no provider for the simple case. Subscriptions wire through useSyncExternalStore, so reads stay tear-free under React 18 concurrent rendering.

Highlighted features

Per-atom hooks

myAtom.useValue(), myAtom.useState(), myAtom.use(“key”). No global hook + atom-as-argument ceremony.

Tear-free under React 18

Built on useSyncExternalStore — safe for concurrent rendering, transitions, and Suspense boundaries.

Preset atoms

openAtom for toggles, loadingAtom for flags, fetchingAtom for the lifecycle, portalAtom for modal-with-payload — the 80% you’d otherwise rewrite per project.

SSR-isolated stores

<AtomStoreProvider> creates a per-request store. Module-level singletons stay safe; per-user state stays scoped.

Install

npm

npm install @mongez/react-atom

yarn

yarn add @mongez/react-atom

pnpm

pnpm add @mongez/react-atom

Peer: react >= 18. @mongez/atom installs automatically.

Quick peek

import { atom } from "@mongez/react-atom";

const counterAtom = atom({ key: "counter", default: 0 });

function Counter() {
  const count = counterAtom.useValue();
  return (
    <button onClick={() => counterAtom.update(count + 1)}>
      Count: {count}
    </button>
  );
}

Every atom carries its own hooks. No useAtomValue(counterAtom) ceremony, no provider needed for client-only apps.

The hooks every atom carries

const userAtom = atom({ key: "user", default: { name: "Anon", age: 0 } });

userAtom.useValue();           // subscribe; returns the whole value
userAtom.useState();           // returns [value, setValue]
userAtom.use("name");          // subscribes to ONE key
userAtom.useWatch("name", cb); // effect-style subscription
<userAtom.Provider value={...} />  // pushes a value into the atom on mount

All four honour the nearest <AtomStoreProvider>. When no provider is mounted, they operate on the module-level singleton — the correct default for client-only apps.

Scope boundaries

Concern	Lives where
Framework-agnostic atom + actions	@mongez/atom
Server-state cache with query keys	@mongez/atomic-query
Event bus	@mongez/events

Where to go next

• Atoms — atom(...), per-atom hooks, custom actions
• Preset atoms — openAtom, loadingAtom, fetchingAtom, portalAtom
• SSR & stores — <AtomStoreProvider>, hydration helpers
• Recipes — toggles, modals, fetch lifecycles, Next.js / Remix / TanStack Start hydration