> ## Documentation Index
> Fetch the complete documentation index at: https://claritylabs.inc/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CL Sync: Local-First React Sync Library

> Render cached records in your React app while fetching updates from your server.

CL Sync (`@claritylabs/cl-sync`) is a browser sync library that renders cached records while fetching updates from your server. Mutations are written to a durable outbox so they survive page reloads and can be retried automatically.

## Key features

> **Instant hydration**
>
> Previously cached records load from IndexedDB without waiting for a server response.

> **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**:

```typescript theme={"system"}
{
  appId: string;       // required — identifies your application
  environment?: string; // e.g. "production" | "staging" | import.meta.env.MODE
  userId?: string;     // isolates data per authenticated user
  orgId?: string;      // further isolates data per organization
}
```

CL Sync calls `createScopeKey(scope)` to derive a composite key like `"todo-app:production:user-123:org-456"`. Records are partitioned by scope within a database named by app and environment. Create a store with the new scope when switching users or organizations. Switching scope does not delete previously stored data.

## Package structure

CL Sync ships three sub-path exports so you only pay for what you import:

| Import path | Contents |
| - | - |
| `@claritylabs/cl-sync` (or `/core`) | `createSyncStore`, `defineCollection`, `defineMutation`, outbox, schema, migrations |
| `@claritylabs/cl-sync/react` | `SyncProvider`, all React hooks |
| `@claritylabs/cl-sync/convex` | `defineConvexCollection`, `defineConvexMutation`, `subscribeConvexCollection` |

Peer dependencies are all optional — install only what you need:

| Peer | Version |
| - | - |
| `react` | `>=18.0.0` |
| `convex` | `>=1.30.0` |

## Install

```bash theme={"system"}
npm install @claritylabs/cl-sync
```

## Next steps

> **[Quickstart](https://claritylabs.inc/docs/cl-sync/quickstart.md)**
>
> Build a working todo app in five steps.

> **[Core Concepts](https://claritylabs.inc/docs/cl-sync/concepts.md)**
>
> Understand scopes, collections, the outbox, and optimistic updates.

> **[Store API](https://claritylabs.inc/docs/cl-sync/store.md)**
>
> Full reference for `createSyncStore` and all store methods.

> **[Convex Adapter](https://claritylabs.inc/docs/cl-sync/convex-adapter.md)**
>
> Wire up real-time Convex queries and mutations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.