@zap-studio/store-react 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0]
+
+### Added
+
+- First release. `useStore(store)` subscribes a component to a `createStore`/`derive` instance and re-renders on every change.
+- `useStore(store, selector)` narrows the subscribed value; the component only re-renders when the selected result changes, compared with `Object.is`.
+- Built on React's `useSyncExternalStore`, so subscriptions are safe under concurrent rendering.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandre Trotel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @zap-studio/store-react
+
+React bindings for [`@zap-studio/store`](https://www.npmjs.com/package/@zap-studio/store): a single `useStore` hook that subscribes a component to a `createStore`/`derive` instance.
+
+Full documentation: [zapstudio.dev/store/react](https://www.zapstudio.dev/store/react)
+
+## Motivation
+
+Zustand's React binding needs a `selector` plus a manual `shallow` equality check to avoid extra re-renders, because Zustand's own state has no built-in way to cache a derived value. `@zap-studio/store` already solves that at the source with `derive` — a computed value that is auto-tracked and cached, and only changes reference when it actually changes.
+
+`@zap-studio/store-react` stays deliberately thin: one hook, built on React's own `useSyncExternalStore`, that reads whatever `@zap-studio/store` gives it. No middleware, no context Provider, no shallow-equality helper to reach for — build the exact value your component needs with `derive`, then subscribe to it.
+
+## Installation
+
+```bash
+npm install @zap-studio/store-react @zap-studio/store
+```
+
+## Features
+
+- **One hook**: `useStore(store, selector?)` — nothing else exported.
+- **Works with both**: a `createStore` instance, or a `derive` value.
+- **Built on `useSyncExternalStore`** — safe under React's concurrent rendering, no custom subscription-in-`useEffect` code.
+- **`selector` is optional** and narrows the subscribed value; the component only re-renders when the selected result changes, compared with `Object.is`.
+
+## Quick Start
+
+```tsx
+import { createStore, derive } from "@zap-studio/store";
+import { useStore } from "@zap-studio/store-react";
+
+const counter = createStore({ count: 0 }, (set) => ({
+  increment: () => set((s) => ({ count: s.count + 1 })),
+}));
+
+function Counter() {
+  const count = useStore(counter, (s) => s.count);
+  return <button onClick={() => counter.get().increment()}>{count}</button>;
+}
+```
+
+## Without a Selector
+
+`useStore(store)` re-renders on every change to `store` — both `createStore` and `derive` results are cached internally, so this is safe either way, it just re-renders on more changes than a selector would:
+
+```tsx
+const isEven = derive([counter], (s) => s.count % 2 === 0);
+
+function Parity() {
+  const even = useStore(isEven);
+  return even ? "even" : "odd";
+}
+```
+
+To avoid re-rendering on changes your component doesn't care about, pass a selector, or build the exact value you need with `derive` first.
+
+## Runtime Support
+
+| Runtime  | Minimum version                                  |
+| -------- | ------------------------------------------------ |
+| React    | 18.0.0                                           |
+| Node.js  | 18.0.0                                           |
+| Bun      | 1.0.0                                            |
+| Deno     | 1.42                                             |
+| Browsers | Latest evergreen (Chrome, Edge, Firefox, Safari) |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { useStore } from "./use-store.js";
+export { useStore };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { useStore } from "./use-store.js";
+export { useStore };

package/dist/use-store.d.ts

@@ -0,0 +1,26 @@
+import { Readable } from "@zap-studio/store";
+//#region src/use-store.d.ts
+/**
+ * Subscribes to a `createStore`/`derive` instance and re-renders when its
+ * value changes.
+ *
+ * Without `selector`, the component re-renders on every change to `store`.
+ * To re-render only on the parts your component actually reads, pass a
+ * `selector` — or build the exact value you need with `derive` first
+ * (`derive([store], (s) => s.count)`), rather than reaching for manual
+ * shallow-equality checks.
+ *
+ * @param store - A `createStore` or `derive` instance.
+ * @param selector - Narrows the subscribed value; re-renders only when its
+ *   result changes (compared with `Object.is`).
+ *
+ * @example
+ * ```tsx
+ * const count = useStore(counter, (s) => s.count);
+ * ```
+ */
+declare function useStore<T>(store: Readable<T>): T;
+declare function useStore<T, U>(store: Readable<T>, selector: (value: T) => U): U;
+//#endregion
+export { useStore };
+//# sourceMappingURL=use-store.d.ts.map

package/dist/use-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-store.d.ts","names":[],"sources":["../src/use-store.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;iBA8BgB,SAAS,GAAG,OAAO,SAAS,KAAK;iBACjC,SAAS,GAAG,GAAG,OAAO,SAAS,IAAI,WAAW,OAAO,MAAM,IAAI"}

package/dist/use-store.js

@@ -0,0 +1,10 @@
+import { useSyncExternalStore } from "react";
+//#region src/use-store.ts
+function useStore(store, selector) {
+	const getSnapshot = () => selector ? selector(store.get()) : store.get();
+	return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
+}
+//#endregion
+export { useStore };
+
+//# sourceMappingURL=use-store.js.map

package/dist/use-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-store.js","names":[],"sources":["../src/use-store.ts"],"sourcesContent":["/**\n * `useStore`: subscribes a React component to a `createStore`/`derive`\n * instance, re-rendering only when the subscribed value actually changes.\n *\n * @module @zap-studio/store-react/use-store\n */\n\nimport type { Readable } from \"@zap-studio/store\";\n\nimport { useSyncExternalStore } from \"react\";\n\n/**\n * Subscribes to a `createStore`/`derive` instance and re-renders when its\n * value changes.\n *\n * Without `selector`, the component re-renders on every change to `store`.\n * To re-render only on the parts your component actually reads, pass a\n * `selector` — or build the exact value you need with `derive` first\n * (`derive([store], (s) => s.count)`), rather than reaching for manual\n * shallow-equality checks.\n *\n * @param store - A `createStore` or `derive` instance.\n * @param selector - Narrows the subscribed value; re-renders only when its\n *   result changes (compared with `Object.is`).\n *\n * @example\n * ```tsx\n * const count = useStore(counter, (s) => s.count);\n * ```\n */\nexport function useStore<T>(store: Readable<T>): T;\nexport function useStore<T, U>(store: Readable<T>, selector: (value: T) => U): U;\nexport function useStore<T, U>(store: Readable<T>, selector?: (value: T) => U): T | U {\n  const getSnapshot = (): T | U => (selector ? selector(store.get()) : store.get());\n  return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);\n}\n"],"mappings":";;AAgCA,SAAgB,SAAe,OAAoB,UAAmC;CACpF,MAAM,oBAA4B,WAAW,SAAS,MAAM,IAAI,CAAC,IAAI,MAAM,IAAI;CAC/E,OAAO,qBAAqB,MAAM,WAAW,aAAa,WAAW;AACvE"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@zap-studio/store-react",
+  "version": "1.0.0",
+  "private": false,
+  "description": "React bindings for @zap-studio/store: a useStore hook that subscribes to a createStore/derive instance.",
+  "keywords": [
+    "derive",
+    "react",
+    "react-hooks",
+    "state",
+    "state-management",
+    "store",
+    "typescript"
+  ],
+  "homepage": "https://www.zapstudio.dev/store/react",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zap-studio/monorepo.git",
+    "directory": "packages/store-react"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./use-store": "./dist/use-store.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepublishOnly": "pnpm -C ../.. run build"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "catalog:",
+    "@testing-library/react": "catalog:",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "@zap-studio/store": "workspace:*",
+    "@zap-studio/typescript": "workspace:*",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "peerDependencies": {
+    "@zap-studio/store": "^1.0.0",
+    "react": ">=18.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}