🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
@mongez/react-atom
Advanced tools
@mongez/react-atom - npm Package Compare versions
+9
-0
@@ -61,2 +61,5 @@ # @mongez/react-atom — full reference | ||
| > **Auto-trigger:** code imports `atom`, `atomCollection`, or `useAtom` from `@mongez/react-atom`; code calls `.useValue()`, `.useState()`, `.use(key)`, `.useWatch(key, cb)`, or renders `<someAtom.Provider>`; user asks "how do I create an atom in React", "what's the difference between useValue and useState", "how do I subscribe to one key only", or "how do I add a custom action to a React atom"; typical import `import { atom, atomCollection } from "@mongez/react-atom"`. | ||
| > **Skip when:** framework-agnostic atom primitive (`createAtom`, `createAtomCollection`) — that lives in `@mongez/atom`, the core layer this package sits on top of; preset-atom shorthands (`openAtom`/`loadingAtom`/`fetchingAtom`/`portalAtom`) use `mongez-react-atom-presets`; per-request SSR scoping and hydration use `mongez-react-atom-ssr`; copy-paste end-to-end flows use `mongez-react-atom-recipes`. | ||
| Same shape as `createAtom` from `@mongez/atom`. Returns a `ReactAtom<V, A>` — a `Atom<V, A>` plus the React-aware actions injected by this package. | ||
@@ -80,2 +83,5 @@ | ||
| > **Auto-trigger:** code imports or calls `openAtom`, `loadingAtom`, `fetchingAtom`, or `portalAtom` from `@mongez/react-atom`; code uses `useOpened`, `useLoading`, `useData`, `useError`, `usePagination`, `startLoading`, `stopLoading`, `toggleLoading`, `success`, `failed`, `append`, `prepend`, or `toggle` methods on a preset atom; user asks "how do I make a toggle / open-close atom", "how do I model a loading flag", "how do I do a fetch lifecycle with isLoading/data/error", or "how do I coordinate a modal/drawer"; typical import `import { openAtom, portalAtom } from "@mongez/react-atom"`. | ||
| > **Skip when:** hand-rolling a custom action atom from scratch — use `mongez-react-atom-atoms`; richer cache-keyed server state (invalidation, refetch on focus) belongs in `@mongez/atomic-query`, not `fetchingAtom`; SSR scoping/hydration of preset atoms still uses `mongez-react-atom-ssr`; end-to-end flow examples use `mongez-react-atom-recipes`. | ||
| ### openAtom(key, defaultOpened = false) | ||
@@ -106,2 +112,5 @@ | ||
| > **Auto-trigger:** code imports `AtomStoreProvider`, `AtomStoreContext`, `useAtom`, `useAtomStore`, `HydrateAtomsScript`, `readHydration`, `serializeStore`, `serializeSnapshot`, `DEFAULT_HYDRATION_SCRIPT_ID`, `AtomStoreProviderProps`, or `HydrateAtomsScriptProps` from `@mongez/react-atom`; user asks "how do I avoid hydration mismatches with atoms in Next.js App Router", "how do I isolate atom state per SSR request", "how do I pre-fill atoms on the server", or "how do I call an action method safely under SSR"; typical import `import { AtomStoreProvider, HydrateAtomsScript, readHydration } from "@mongez/react-atom"`. | ||
| > **Skip when:** client-only single-page apps where module-level singletons are fine — no provider needed, so reach for `mongez-react-atom-atoms` instead; preset atoms in a non-SSR context use `mongez-react-atom-presets`; the underlying store primitive `createAtomStore` and `snapshot()` itself live in `@mongez/atom`, the core layer this package wraps; mixed end-to-end flows use `mongez-react-atom-recipes`. | ||
| ### `<AtomStoreProvider>` | ||
@@ -108,0 +117,0 @@ |
+5
-0
@@ -10,2 +10,3 @@ # @mongez/react-atom | ||
| - [Overview](https://raw.githubusercontent.com/hassanzohdy/mongez-react-atom/main/skills/overview.md): Pitch, install, the hooks every atom carries. | ||
| - *Auto-trigger:* Any import from `@mongez/react-atom` or a "what is this package / how does it relate to @mongez/atom" question. | ||
| - [README](https://raw.githubusercontent.com/hassanzohdy/mongez-react-atom/main/README.md): Usage and recipes. | ||
@@ -17,5 +18,9 @@ - [Changelog](https://raw.githubusercontent.com/hassanzohdy/mongez-react-atom/main/CHANGELOG.md): Release notes. | ||
| - [Atoms in React](https://raw.githubusercontent.com/hassanzohdy/mongez-react-atom/main/skills/atoms.md): `atom(...)` factory, per-atom hooks (`useState`, `useValue`, `use(key)`, `useWatch`, `Provider`). | ||
| - *Auto-trigger:* Importing `atom`/`atomCollection` or calling `.useValue`/`.useState`/`.use(key)`/`.useWatch`/`.Provider` on an atom. | ||
| - [Preset atoms](https://raw.githubusercontent.com/hassanzohdy/mongez-react-atom/main/skills/presets.md): `openAtom`, `loadingAtom`, `fetchingAtom`, `portalAtom`. | ||
| - *Auto-trigger:* Importing `openAtom`/`loadingAtom`/`fetchingAtom`/`portalAtom`, or modeling a toggle, loading flag, fetch lifecycle, or modal coordinator. | ||
| - [SSR & stores](https://raw.githubusercontent.com/hassanzohdy/mongez-react-atom/main/skills/ssr.md): `<AtomStoreProvider>`, `useAtom(template | key)`, `useAtomStore()`, `serializeStore`, `<HydrateAtomsScript>`, `readHydration`. | ||
| - *Auto-trigger:* Using `AtomStoreProvider`/`useAtom`/`useAtomStore`/`HydrateAtomsScript`/`readHydration`, or asking about per-request isolation or hydration mismatches. | ||
| - [Recipes](https://raw.githubusercontent.com/hassanzohdy/mongez-react-atom/main/skills/recipes.md): Toggle/modal patterns, fetch lifecycles, Next.js / Remix / TanStack Start hydration. | ||
| - *Auto-trigger:* Asking for a working end-to-end example combining preset atoms, providers, or hydration — not a single-API reference. | ||
@@ -22,0 +27,0 @@ ## Quick rules |
+1
-1
@@ -27,3 +27,3 @@ { | ||
| }, | ||
| "version": "6.0.2", | ||
| "version": "6.0.3", | ||
| "main": "./cjs/index.cjs", | ||
@@ -30,0 +30,0 @@ "module": "./esm/index.mjs", |
| --- | ||
| name: mongez-react-atom-atoms | ||
| description: How to create atoms and atomCollections in React and use their per-instance hooks (useValue, useState, use, useWatch, Provider) and custom actions. | ||
| when_to_use: User calls atom() or atomCollection() from "@mongez/react-atom", user uses any per-atom hook (useValue/useState/use/useWatch) or the atom's Provider component, user defines custom actions on a React atom, user wants granular per-key subscriptions with use(), user asks about the difference between useValue and useState or when to prefer each. | ||
| description: | | ||
| How to create atoms and atomCollections in React and use their per-instance hooks (`useValue`, `useState`, `use`, `useWatch`, `Provider`) and custom actions. | ||
| TRIGGER when: code imports `atom`, `atomCollection`, or `useAtom` from `@mongez/react-atom`; code calls `.useValue()`, `.useState()`, `.use(key)`, `.useWatch(key, cb)`, or renders `<someAtom.Provider>`; user asks "how do I create an atom in React", "what's the difference between useValue and useState", "how do I subscribe to one key only", or "how do I add a custom action to a React atom"; typical import `import { atom, atomCollection } from "@mongez/react-atom"`. | ||
| SKIP: framework-agnostic atom primitive (`createAtom`, `createAtomCollection`) — that lives in `@mongez/atom`, the core layer this package sits on top of; preset-atom shorthands (`openAtom`/`loadingAtom`/`fetchingAtom`/`portalAtom`) use `mongez-react-atom-presets`; per-request SSR scoping and hydration use `mongez-react-atom-ssr`; copy-paste end-to-end flows use `mongez-react-atom-recipes`. | ||
| --- | ||
@@ -6,0 +8,0 @@ # Atoms in React |
| --- | ||
| name: mongez-react-atom-overview | ||
| description: High-level overview of @mongez/react-atom — what it exports, how its React hooks and AtomStoreProvider work, and where it fits relative to @mongez/atom and other packages. | ||
| when_to_use: User asks what @mongez/react-atom is or how it works, user sees an import from "@mongez/react-atom" and wants to understand the package, user asks which hooks an atom exposes (useValue/useState/use/useWatch/Provider), user asks about React 18 useSyncExternalStore integration, user wants to understand AtomStoreProvider scope boundaries. | ||
| description: | | ||
| High-level overview of `@mongez/react-atom` — what it exports, how its React hooks and `AtomStoreProvider` work, and where it fits relative to `@mongez/atom` and other packages. | ||
| TRIGGER when: code imports `atom`, `atomCollection`, `openAtom`, `loadingAtom`, `fetchingAtom`, `portalAtom`, `AtomStoreProvider`, `AtomStoreContext`, `useAtom`, `useAtomStore`, `HydrateAtomsScript`, `readHydration`, `serializeStore`, `serializeSnapshot`, `ReactAtom`, or `ReactActions` from `@mongez/react-atom`; user asks "what is @mongez/react-atom", "which hooks does an atom expose", "how does it relate to @mongez/atom", or "does it work with React 18 useSyncExternalStore"; typical import `import { atom, AtomStoreProvider } from "@mongez/react-atom"`. | ||
| SKIP: deep-dives on a specific feature — atom factory and per-atom hooks use `mongez-react-atom-atoms`, preset atoms use `mongez-react-atom-presets`, SSR/hydration uses `mongez-react-atom-ssr`, copy-paste flows use `mongez-react-atom-recipes`; the framework-agnostic atom primitive lives in `@mongez/atom`; server-state caching belongs in `@mongez/atomic-query`. | ||
| --- | ||
@@ -6,0 +8,0 @@ # Overview |
| --- | ||
| name: mongez-react-atom-presets | ||
| description: Pre-built atom shapes — openAtom (boolean toggle), loadingAtom (loading flag), fetchingAtom (full fetch lifecycle), and portalAtom (modal/drawer coordinator) — and when to reach for each. | ||
| when_to_use: User imports or calls openAtom/loadingAtom/fetchingAtom/portalAtom from "@mongez/react-atom", user needs a toggle/open-close atom, user needs a loading flag atom, user needs a fetch-lifecycle atom with isLoading/data/error state, user needs a modal or drawer coordinator atom with open/close/data. | ||
| description: | | ||
| Pre-built atom shapes — `openAtom` (boolean toggle), `loadingAtom` (loading flag), `fetchingAtom` (full fetch lifecycle), and `portalAtom` (modal/drawer coordinator) — and when to reach for each. | ||
| TRIGGER when: code imports or calls `openAtom`, `loadingAtom`, `fetchingAtom`, or `portalAtom` from `@mongez/react-atom`; code uses `useOpened`, `useLoading`, `useData`, `useError`, `usePagination`, `startLoading`, `stopLoading`, `toggleLoading`, `success`, `failed`, `append`, `prepend`, or `toggle` methods on a preset atom; user asks "how do I make a toggle / open-close atom", "how do I model a loading flag", "how do I do a fetch lifecycle with isLoading/data/error", or "how do I coordinate a modal/drawer"; typical import `import { openAtom, portalAtom } from "@mongez/react-atom"`. | ||
| SKIP: hand-rolling a custom action atom from scratch — use `mongez-react-atom-atoms`; richer cache-keyed server state (invalidation, refetch on focus) belongs in `@mongez/atomic-query`, not `fetchingAtom`; SSR scoping/hydration of preset atoms still uses `mongez-react-atom-ssr`; end-to-end flow examples use `mongez-react-atom-recipes`. | ||
| --- | ||
@@ -6,0 +8,0 @@ # Preset atoms |
| --- | ||
| name: mongez-react-atom-recipes | ||
| description: Concrete copy-paste recipes for common @mongez/react-atom patterns: toggles, modals with payload, fetch flows, granular subscriptions, SSR hydration, SSR-safe action handlers, and devtools setup. | ||
| when_to_use: User wants a working example of a specific @mongez/react-atom pattern, user asks how to wire up a modal with portalAtom, user asks how to do a fetch flow with fetchingAtom, user asks how to subscribe to a single object key, user asks how to call an action method from an event handler safely under SSR, user wants to enable Redux DevTools for atoms. | ||
| description: | | ||
| Concrete copy-paste recipes for common `@mongez/react-atom` patterns: toggles, modals with payload, fetch flows, granular subscriptions, SSR hydration, SSR-safe action handlers, and devtools setup. | ||
| TRIGGER when: code mixes preset atoms (`openAtom`, `portalAtom`, `fetchingAtom`) with handlers, `AtomStoreProvider` + `HydrateAtomsScript` + `readHydration`, or calls `useAtom(template)` from an event handler; user asks "how do I wire up a modal with portalAtom", "how do I do a fetch flow with fetchingAtom", "how do I subscribe to a single object key", "how do I call an action method safely under SSR", or "how do I enable Redux DevTools for atoms"; user wants a working end-to-end example, not just an API description; typical import `import { openAtom, portalAtom, fetchingAtom, useAtom } from "@mongez/react-atom"`. | ||
| SKIP: a single-API reference (use `mongez-react-atom-atoms`, `mongez-react-atom-presets`, or `mongez-react-atom-ssr` instead — recipes is for combined patterns); the underlying framework-agnostic atom primitive lives in `@mongez/atom`; server-state caching with query keys belongs in `@mongez/atomic-query`. | ||
| --- | ||
@@ -6,0 +8,0 @@ # Recipes |
| --- | ||
| name: mongez-react-atom-ssr | ||
| description: How to use AtomStoreProvider, useAtom, useAtomStore, and the hydration utilities (HydrateAtomsScript, readHydration, serializeStore, serializeSnapshot) for SSR-safe, per-request atom isolation and client hydration. | ||
| when_to_use: User uses AtomStoreProvider or needs per-request atom isolation in SSR, user imports useAtom/useAtomStore from "@mongez/react-atom", user calls HydrateAtomsScript or readHydration, user asks how to avoid hydration mismatches with atom state in Next.js App Router or any SSR framework, user needs to pre-fill atoms on the server and transfer state to the client. | ||
| description: | | ||
| How to use `AtomStoreProvider`, `useAtom`, `useAtomStore`, and the hydration utilities (`HydrateAtomsScript`, `readHydration`, `serializeStore`, `serializeSnapshot`) for SSR-safe, per-request atom isolation and client hydration. | ||
| TRIGGER when: code imports `AtomStoreProvider`, `AtomStoreContext`, `useAtom`, `useAtomStore`, `HydrateAtomsScript`, `readHydration`, `serializeStore`, `serializeSnapshot`, `DEFAULT_HYDRATION_SCRIPT_ID`, `AtomStoreProviderProps`, or `HydrateAtomsScriptProps` from `@mongez/react-atom`; user asks "how do I avoid hydration mismatches with atoms in Next.js App Router", "how do I isolate atom state per SSR request", "how do I pre-fill atoms on the server", or "how do I call an action method safely under SSR"; typical import `import { AtomStoreProvider, HydrateAtomsScript, readHydration } from "@mongez/react-atom"`. | ||
| SKIP: client-only single-page apps where module-level singletons are fine — no provider needed, so reach for `mongez-react-atom-atoms` instead; preset atoms in a non-SSR context use `mongez-react-atom-presets`; the underlying store primitive `createAtomStore` and `snapshot()` itself live in `@mongez/atom`, the core layer this package wraps; mixed end-to-end flows use `mongez-react-atom-recipes`. | ||
| --- | ||
@@ -6,0 +8,0 @@ # SSR & stores |
No alert changes
Improved metrics
- Total package byte prevSize
143990
4.81%No dependency changes