@kitr/state 0.3.1 → 0.4.0

package/dist/index.d.ts

@@ -10,11 +10,17 @@ export interface KitrStoreOptions<T> {
   persist?: Partial<PersistOptions<T, Partial<T>>> | boolean;
   /** Connect to the Redux DevTools extension in development. Default `true`; never in production or on the server. */
   devtools?: boolean;
+  /**
+   * Throw when a component reads the store on the server outside its `<StoreProvider>`, instead of
+   * rendering a fresh copy of the initial state. Default `false`.
+   */
+  strict?: boolean;
 }
 /**
  * An SSR-safe Zustand store factory. On the client the store is a module-level
  * singleton; on the server (or in tests) you get a fresh store per `<StoreProvider>`,
- * so one user's state never leaks into another's render.
+ * so one user's state never leaks into another's render. Without a provider, each component
+ * that reads the store on the server gets its own fresh store, built from the initial state.
  *
  *   const [useCounter, CounterProvider, counterStore] = createKitrStore({ name: 'counter' }, (set) => ({ ... }))
  */

package/dist/index.js

@@ -7,7 +7,8 @@ export * from "zustand";
 /**
 * An SSR-safe Zustand store factory. On the client the store is a module-level
 * singleton; on the server (or in tests) you get a fresh store per `<StoreProvider>`,
-* so one user's state never leaks into another's render.
+* so one user's state never leaks into another's render. Without a provider, each component
+* that reads the store on the server gets its own fresh store, built from the initial state.
 *
 *   const [useCounter, CounterProvider, counterStore] = createKitrStore({ name: 'counter' }, (set) => ({ ... }))
 */
@@ -54,8 +55,14 @@ function createKitrStore(options, initializer) {
 		});
 	}
 	function useKitrStore(selector) {
-		const store = useContext(Context) ?? singleton;
-		if (!store) throw new Error(`[@kitr/state] Store "${options.name}" has no instance on the server. Wrap the tree in its <StoreProvider>.`);
+		const fromContext = useContext(Context);
+		const own = useRef(null);
+		let store = fromContext ?? singleton;
+		if (!store) {
+			if (options.strict) throw new Error(`[@kitr/state] Store "${options.name}" has no instance on the server. Wrap the tree in its <StoreProvider>.`);
+			own.current ??= build();
+			store = own.current;
+		}
 		const select = selector ?? ((s) => s);
 		const snapshot = () => select(store.getState());
 		const serverSnapshot = options.persist && store === singleton ? () => select(renderedOnServer(store)) : snapshot;

package/dist/kitr.d.ts

@@ -13,6 +13,7 @@ declare const _default: {
         vars: Record<string, string>;
       };
       readonly stub: ({ name }: import("@kitr/core/package").GeneratorVars) => string;
+      readonly after: (ctx: import("@kitr/core/package").AddContext) => void;
     };
   };
   readonly wraps: {

package/dist/kitr.js

@@ -7,7 +7,7 @@ var kitr_default = definePackage({
 	add(ctx) {
 		ctx.deps.add("zustand");
 		ctx.write("app/stores/.gitkeep", "");
-		ctx.agents.add("state", `- Client state only. \`kitr make:store <name>\` writes \`app/stores/<name>.ts\` using \`createKitrStore\`. Server data belongs in queries, not stores.`);
+		ctx.agents.add("state", `- Client state only. \`kitr make:store <name>\` writes \`app/stores/<name>.ts\` using \`createKitrStore\`. On the server, wrap the components that use it in its \`<NameStoreProvider>\` to share one store per render; without it each component renders the initial state. Server data belongs in queries, not stores.`);
 	},
 	remove(ctx) {
 		ctx.deps.remove("zustand");
@@ -25,6 +25,11 @@ interface ${naming.pascal(name)}State {
   reset: () => void
 }
 
+/**
+ * In the browser \`use${naming.pascal(name)}Store()\` needs no provider. On the server, wrap the
+ * components that call it in \`<${naming.pascal(name)}StoreProvider>\` so they share one store per
+ * render; without it each one renders the initial state.
+ */
 export const [use${naming.pascal(name)}Store, ${naming.pascal(name)}StoreProvider, ${naming.camel(name)}Store] = createKitrStore<${naming.pascal(name)}State>(
   { name: '${naming.snake(name)}', persist: false },
   (set) => ({
@@ -33,7 +38,11 @@ export const [use${naming.pascal(name)}Store, ${naming.pascal(name)}StoreProvide
     reset: () => set({ count: 0 }),
   }),
 )
-`
+`,
+		after(ctx) {
+			const keep = `${ctx.rc.directories.app ?? "app"}/stores/.gitkeep`;
+			if (ctx.exists(keep)) ctx.unlink(keep);
+		}
 	} },
 	wraps: { zustand: "@kitr/state" },
 	eject: { "@kitr/state": "zustand" },

package/docs/api.md

@@ -26,6 +26,7 @@ Creates a store that is a singleton in the browser and per-provider on the serve
 | `name` | `string` | required | Used for devtools and as the storage key `kitr:<name>`. |
 | `persist` | `boolean \| PersistOptions` | `false` | Save to `localStorage`. An object is passed to Zustand's `persist` middleware; its `name` overrides the storage key. |
 | `devtools` | `boolean` | `true` in dev | Connect to Redux DevTools in development. |
+| `strict` | `boolean` | `false` | Throw on the server when the hook runs outside a `StoreProvider`. |
 
 ### Returns
 
@@ -34,12 +35,12 @@ A tuple. Name the parts whatever suits your store.
 | Position | Value | Description |
 | --- | --- | --- |
 | 0 | `useStore()` / `useStore(selector)` | Hook. Without a selector it returns the whole state. |
-| 1 | `StoreProvider` | Component with `children` and optional `initialState: Partial<T>`. Required on the server. |
+| 1 | `StoreProvider` | Component with `children` and optional `initialState: Partial<T>`. Shares one store per server render. |
 | 2 | `store` | The browser's `StoreApi<T>`, or `null` on the server. |
 
 ### Errors
 
-Calling the hook on the server without a surrounding `StoreProvider` throws:
+Without a surrounding `StoreProvider`, the hook on the server reads a fresh store of the component's own, built from the initial state. With `strict: true` it throws instead:
 
 ```
 [@kitr/state] Store "cart" has no instance on the server. Wrap the tree in its <StoreProvider>.

package/docs/index.md

@@ -93,13 +93,14 @@ export const [usePreferences, PreferencesProvider, preferencesStore] =
 | `persist.version` | `0` | The saved shape's version. Saved data with another version goes through `migrate`, or is dropped without one. |
 | `persist.migrate` | none | A function `(saved, version) => state` that upgrades old saved data. |
 | `devtools` | `true` | Connects to the Redux DevTools in development; `false` leaves it out. |
+| `strict` | `false` | Throws on the server when a component reads the store outside its `StoreProvider`. |
 
 The second argument is a Zustand state creator: it gets `set`, `get` and the store, and returns the initial state with its actions. `createKitrStore` returns three things, in this order:
 
 | Value | Description |
 | --- | --- |
 | `useStore` | The hook. `useStore(selector)` returns a slice; `useStore()` returns the whole state. |
-| `StoreProvider` | A component that gives its subtree a store. Needed on the server; optional in the browser. Takes `initialState`. |
+| `StoreProvider` | A component that gives its subtree a store. Shares one store per server render; optional in the browser. Takes `initialState`. |
 | `store` | The browser's store instance, for code outside components. `null` on the server. |
 
 
@@ -457,8 +458,13 @@ One server process renders pages for many users, so a module-level store would l
 
 - **In the browser**, the store is one module-level instance, read without a provider.
 - **On the server**, each `<StoreProvider>` creates a fresh store for its render, and storage is never touched.
+- **On the server without a provider**, each component that reads the store gets its own fresh store, built from the initial state and dropped with the render.
 
-If a page renders on the server (`ssr` or `static` mode), wrap the part of the tree that reads the store:
+So a page renders on the server with or without a provider, and no state outlives the request. Without a provider nothing is shared either: a write during the server render reaches only the component that made it. Effects and event handlers run in the browser, where the one store is shared as usual.
+
+### Static and SSR
+
+To share one store across a server render, for example to seed it with `initialState`, wrap the part of the tree that reads it:
 
 ```tsx
 // app/document.tsx
@@ -482,7 +488,9 @@ export function RootDocument() {
 }
 ```
 
-Without a provider, the server render fails with:
+In a client-only app (`spa` mode, desktop, mobile) skip the provider.
+
+To make a missing provider an error instead, pass `strict: true`. The server render then fails with:
 
 ```txt
 [@kitr/state] Store "order-draft" has no instance on the server. Wrap the tree in its <StoreProvider>.
@@ -490,6 +498,10 @@ Without a provider, the server render fails with:
 
 In a client-only app (`spa` mode, desktop, mobile) skip the provider.
 
+### Static and SSR
+
+A `static` site is rendered on the server too: `kitr build` prerenders every page there, so the same rules apply as in an `ssr` app. Without a provider each component that reads the store gets its own fresh copy of the initial state for that render, which is fine for a widget that owns its state and wrong for two components that are meant to share it. To share, wrap them in one line in `app/document.tsx`, `<OrderDraftProvider><Outlet /></OrderDraftProvider>`; it is harmless in the browser, where the provider is optional. Set `strict: true` on the store to get an error instead of the fallback.
+
 <details>
 <summary>Persisted stores and hydration</summary>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitr/state",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "@kitr/state: Zustand re-exported, plus an SSR-safe store factory.",
   "kitr": {
     "name": "state",
@@ -44,7 +44,7 @@
     "docs"
   ],
   "dependencies": {
-    "@kitr/core": "0.3.1"
+    "@kitr/core": "0.4.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0",