@claritylabs/cl-sync) is a local-first browser sync library that makes your React app feel instant. On every page load, your UI hydrates from a scoped IndexedDB cache before any network request completes, then quietly reconciles with the server in the background. Mutations are written to a durable outbox so they survive page reloads and can be retried automatically.
Key features
Instant hydration
Records load from IndexedDB on boot — no waiting for a server response before rendering.
Scoped persistence
Data is isolated by
appId, environment, userId, and orgId. Switching users or orgs creates a completely separate IndexedDB scope.Optimistic mutations
A
reducer applies your mutation locally before the network call. A durable outbox tracks every mutation through reloads and retries.React hooks
useSyncCollection, useSyncRecord, useSyncMutation, and useSyncStatus give you reactive, type-safe access to all sync state.Convex adapter
First-class support for Convex: subscribe to real-time queries, wrap Convex mutations, and let the adapter handle snapshot diffing.
Schema migrations
Declare versioned migrations that run during
hydrate(). Rename fields, transform records, and prune stale outbox entries safely.How scoping works
Every store is tied to a scope object:createScopeKey(scope) to derive a composite key like "todo-app:production:user-123:org-456". Each unique scope key maps to its own IndexedDB database. When you swap userId (logout → login), the store automatically works against a fresh scope — no manual cleanup required.
Package structure
CL Sync ships three sub-path exports so you only pay for what you import:
Peer dependencies are all optional — install only what you need:
Install
Next steps
Quickstart
Build a working todo app in five steps.
Core Concepts
Understand scopes, collections, the outbox, and optimistic updates.
Store API
Full reference for
createSyncStore and all store methods.Convex Adapter
Wire up real-time Convex queries and mutations.