react-persist
Gate React UI on Persist hydration with useHydrated + toHydrationSignal. Use when avoiding flash of default state on async backends (IndexedDB), SSR snapshot true, or wiring HydrationSignal into React 18/19.
- License 许可
- MIT
- 最近更新
- 2026-11-01
- Stars
- ★ 5
- Forks
- 0
01 前言 Front Matter
- name
- react-persist
- license
- MIT
- sources
- [ "stainless-code/persist:src/adapters/frameworks/react.ts", "stainless-code/persist:docs/architecture.md" ]
- metadata
- { "type": "framework", "library": "@stainless-code/persist", "framework": "react", "library_version": "0.4.1" }
- requires
- [ "persist" ]
- description
- Gate React UI on Persist hydration with useHydrated + toHydrationSignal. Use when avoiding flash of default state on async backends (IndexedDB), SSR snapshot true, or wiring HydrationSignal into React 18/19.
03 SKILL.md 正文
React hydration gate
@stainless-code/persist/frameworks/react exports useHydrated(signal) — a thin useSyncExternalStore wrapper over HydrationSignal. It does not persist state; pair it with a ./sources/* adapter (persist-zustand, persist-tanstack-store, …).
When to use this skill
- Async backend (IndexedDB) — gate UI until hydrate settles.
- SSR — server snapshot is always
hydrated: true(nothing to wait for server-side). null/undefinedsignal → treat as hydrated (no persistence configured).
Install
bun add @stainless-code/persist react
react ^18 || ^19 is the optional peer of /frameworks/react.
Minimal wiring
// store module
import { toHydrationSignal } from "@stainless-code/persist";
import { persistStore } from "@stainless-code/persist/sources/zustand";
const persist = persistStore(store, { name: "app:prefs:v1", storage });
export const prefsHydration = toHydrationSignal(persist);
// component
import { useHydrated } from "@stainless-code/persist/frameworks/react";
const { hydrated } = useHydrated(prefsHydration);
const prefs = useStore(store); // your selector — not from useHydrated
if (!hydrated) return <Skeleton />;
return <PrefsView prefs={prefs} />;
Contracts
- Return shape is only
{ hydrated: boolean }— read state via your store's selector. - Gates UI flash, not store reads; pre-hydration
getState()can still see defaults. - Sync backends settle in a microtask; module-load stores usually hydrate before first paint, but
useHydratedis still the safe read.
Common mistakes
- Treating
useHydratedas the state source. It only reports the gate. - Expecting
hydrated: falseon the server. SSR snapshot istrue. - Forgetting
toHydrationSignal(persist). Pass aHydrationSignal, notPersistApi. - Assuming
nullsignal means “loading”. It means “no persist” → hydrated.
API surface
useHydrated(signal: HydrationSignal | null | undefined) → { hydrated: boolean }- Core helper:
toHydrationSignal(persist)from@stainless-code/persist
See also: the matching persist-* source skill for your store.
04 同仓库更多 Skills
vue-persist
Gate Vue 3 UI on Persist hydration with useHydrated (shallowRef). Use in setup/effectScope when avoiding flash of default state on async backends.
svelte-store-persist
Gate Svelte store-based UI on Persist hydration with hydratedStore (Readable). Use for Svelte 3–4 or Svelte 5 apps that still use stores; runes UI → svelte-persist.
svelte-persist
Gate Svelte 5 runes UI on Persist hydration with hydratedRune (.current). Use for Svelte 5; for stores / Svelte 3–4 use svelte-store-persist.
solid-persist
Gate Solid UI on Persist hydration with useHydrated (Accessor). Use when avoiding flash of default state on async backends; read hydrated() in reactive scopes.
preact-persist
Gate Preact UI on Persist hydration with useHydrated (preact/compat useSyncExternalStore). Use when avoiding flash of default state on async backends or wiring HydrationSignal into Preact.
persist
Core @stainless-code/persist concepts — persistSource, PersistOptions, PersistApi, hydration gate, throttle, cross-tab, migrate. Load before framework hydration skills or when wiring a custom PersistableSource.