@stratasync/react

React bindings and hooks for the sync engine.

Overview

sync-react provides React hooks for data fetching, real-time updates, and collaborative editing:

• SyncProvider: Context provider for the sync client
• useModel / useQuery: Data fetching with Suspense or loading states
• useConnectionState: Monitor sync connection status
• useYjsDocument / useYjsPresence: Collaborative editing and presence

Installation

npm install @stratasync/react

Peer dependencies: react ^18.0.0 || ^19.0.0, yjs ^13.6.0 (for collaborative features)

Setup

Wrap your app with SyncProvider:

import { SyncProvider } from "@stratasync/react";
import { client } from "./sync-client";

function App() {
  return (
    <SyncProvider client={client}>
      <YourApp />
    </SyncProvider>
  );
}

Hooks

Data Fetching

// Single model with Suspense (throws promise while loading)
const task = useModel("Task", taskId);

// Single model with loading state (no Suspense)
const { data: task, isLoading } = useModelState("Task", taskId);

// Filtered query
const { data: tasks, isLoading } = useQuery("Task", {
  where: (i) => i.workspaceId === workspaceId && !i.completedAt,
  limit: 50,
});

// Skip query conditionally
const { data } = useQuery("Task", { skip: !workspaceId });

Connection State

const { status, lastSyncId, backlog, error } = useConnectionState();
// status: "disconnected" | "connecting" | "bootstrapping" | "syncing" | "error"

Collaborative Editing (Yjs)

const { doc, isConnected, participants, content } = useYjsDocument(
  { entityType: "Task", entityId: taskId, fieldName: "description" },
  { autoConnect: true }
);

Package Structure

src/
├── hooks/
│   ├── use-sync-client.ts       Access SyncClient instance
│   ├── use-model.ts             Single model (Suspense)
│   ├── use-query.ts             Filtered queries
│   ├── use-connection-state.ts  Connection monitoring
│   ├── use-yjs-document.ts      Collaborative editing
│   └── use-yjs-presence.ts      Presence tracking
├── provider.tsx                 SyncProvider component
├── context.ts                   React context
└── types.ts                     Type definitions