shared-state-bridge 1.0.0 → 1.0.1

package/README.md

@@ -1,14 +1,41 @@
-# shared-state-bridge
+# Share React State Across Packages in Turborepo & Nx Monorepos | shared-state-bridge
 
-Lightweight shared state bridge for monorepo apps. Sync state across packages in Turborepo / Nx with TypeScript-first API, React hooks, optional persistence, and real-time WebSocket sync across apps.
+Share state between packages in a React monorepo without prop drilling, context threading, or Redux boilerplate. `shared-state-bridge` is a cross-package state store for Turborepo, Nx, and Lerna monorepos -- with React 18 hooks, WebSocket real-time sync, and optional localStorage/AsyncStorage persistence.
 
-- **Zero-config cross-package sharing** — named bridges resolve via global registry
-- **React 18+ hooks** — `useSyncExternalStore` with selector-based re-render optimization
-- **Optional persistence** — localStorage, AsyncStorage, or custom adapters
-- **Real-time sync** — WebSocket-based state sync across different apps (Next.js + React Native)
-- **Tiny** — core ~1.2KB gzipped, no dependencies
-- **TypeScript-first** — full type inference and safety
-- **Plugin system** — extend with persistence, sync, logging, or your own plugins
+> Monorepo state management for React -- create a named store in one package, access it by name from any other. ~1.2 KB core, zero dependencies, full TypeScript inference.
+
+- **Share React state across packages** -- named bridges resolve via a global registry, accessible from any package in your monorepo
+- **React 18 hooks with selector optimization** -- `useSyncExternalStore` with fine-grained re-render control
+- **Persist state to localStorage or AsyncStorage** -- built-in adapters for web and React Native, or write your own
+- **Real-time WebSocket state sync between apps** -- sync state across Next.js, React Native, and any other connected client
+- **~1.2 KB gzipped core, zero dependencies** -- tree-shakeable entry points for React hooks, persistence, and sync
+- **Full TypeScript inference and safety** -- typed `setState`, typed selectors, typed plugins
+- **Extensible plugin system** -- persistence, sync, logging, validation, or your own custom plugins
+
+## Why Use a Cross-Package State Store in a Monorepo?
+
+In Turborepo, Nx, and Lerna monorepos, multiple packages often need to share runtime state -- authentication tokens, user preferences, feature flags, real-time collaboration data. The typical workarounds all have costs: lifting state into a shared package creates tight coupling, duplicating stores across packages leads to drift, and wiring up Redux or Zustand across package boundaries requires manual plumbing that breaks as the monorepo scales.
+
+`shared-state-bridge` solves this with a named global registry. Call `createBridge('auth', initialState)` in one package, call `getBridge('auth')` from any other -- same store instance, same state, no imports needed beyond the type. The registry uses `Symbol.for` internally, so it works even when multiple copies of the library exist in `node_modules` (a common monorepo pitfall).
+
+### How shared-state-bridge Compares
+
+| Feature | shared-state-bridge | Zustand | Redux Toolkit | Jotai |
+|---|---|---|---|---|
+| Cross-package registry | Yes (named bridges) | No | No | No |
+| Monorepo / Turborepo / Nx | First-class | Manual wiring | Manual wiring | Manual wiring |
+| React 18 `useSyncExternalStore` | Yes | Yes | Yes | Yes |
+| Real-time WebSocket sync | Built-in plugin | No | No | No |
+| Persistence plugin | Built-in | Middleware | Redux Persist | No |
+| Bundle size (full) | ~5.1 KB gzipped | ~1 KB | ~11 KB | ~3 KB |
+| TypeScript-first | Yes | Yes | Yes | Yes |
+| Dependencies | Zero | Zero | Several | Zero |
+
+**vs Zustand:** Zustand is a general-purpose state manager for a single package. `shared-state-bridge` adds a named global registry so any package in the monorepo can call `getBridge('app')` and get the same store instance — no prop drilling, no manual exports. If you only need state within one package, Zustand is a great choice.
+
+**vs Redux / Redux Toolkit:** Redux works well for large apps with complex update logic. `shared-state-bridge` trades Redux's reducer boilerplate for a simpler `setState` API, and adds cross-package and WebSocket sync out of the box at a fraction of the bundle cost.
+
+**vs Jotai:** Jotai's atom model is elegant for fine-grained reactivity within a package. `shared-state-bridge` targets a different problem: sharing a named, structured state object across package boundaries in a monorepo, with optional real-time sync.
 
 ---
 
@@ -66,7 +93,6 @@ Lightweight shared state bridge for monorepo apps. Sync state across packages in
   - [Sync Flow](#sync-flow)
 - [Gotchas and Common Pitfalls](#gotchas-and-common-pitfalls)
 - [FAQ](#faq)
-- [Contributing](#contributing)
 - [Support](#support)
 - [License](#license)
 
@@ -1895,66 +1921,6 @@ State persists locally AND syncs in real-time with other connected apps.
 
 ---
 
-## Contributing
-
-Contributions are welcome! Here's how to get started:
-
-```bash
-# Clone the repo
-git clone https://github.com/your-username/shared-state-bridge.git
-cd shared-state-bridge
-
-# Install dependencies
-npm install
-
-# Run tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-
-# Type check
-npm run typecheck
-
-# Build
-npm run build
-```
-
-### Project Structure
-
-```
-src/
-├── index.ts              # Core entry point
-├── core/
-│   ├── types.ts          # All TypeScript type definitions
-│   ├── utils.ts          # shallowEqual, throttle, isFunction
-│   ├── registry.ts       # Global bridge registry
-│   └── bridge.ts         # createBridge + Bridge store logic
-├── react/
-│   ├── index.ts          # React entry point
-│   ├── context.ts        # React context
-│   ├── provider.tsx      # BridgeProvider component
-│   └── hooks.ts          # useBridgeState, useBridge
-├── persist/
-│   ├── index.ts          # Persist entry point
-│   ├── plugin.ts         # Persistence plugin
-│   └── adapters.ts       # Storage adapters
-└── sync/
-    ├── index.ts          # Sync entry point
-    ├── types.ts          # SyncOptions, wire protocol types
-    ├── connection.ts     # WebSocket manager (reconnect, buffer)
-    └── plugin.ts         # sync() plugin factory
-```
-
-### Guidelines
-
-- Keep the core dependency-free
-- Maintain 100% TypeScript strict mode compliance
-- Write tests for all new features
-- Keep bundle sizes minimal — every byte counts
-
----
-
 ## Support
 
 If you find this package useful, consider buying me a coffee!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shared-state-bridge",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Lightweight shared state bridge for monorepo apps — sync state across packages with TypeScript, React hooks, and optional persistence",
   "license": "MIT",
   "type": "module",