App Router compatible sync provider with loading states and error handling.
"use client";
import { NextSyncProvider } from "@stratasync/next";
import { createSyncClient } from "@stratasync/client";
const client = createSyncClient({
/* ... */
});
function Providers({ children }: { children: React.ReactNode }) {
return (
<NextSyncProvider
client={client}
loading={<FullPageSpinner />}
error={(err) => <ErrorPage message={err.message} />}
onReady={() => console.log("Sync ready")}
onError={(err) => console.error("Sync failed", err)}
>
{children}
</NextSyncProvider>
);
}Signature: NextSyncProvider(props: NextSyncProviderProps): ReactNode
| Prop | Type | Default | Description |
|---|---|---|---|
client | SyncClient | (() => SyncClient) | Required | Sync client instance or lazy factory. |
children | ReactNode | Required | Child components. |
loading | ReactNode | null | Shown while the client initializes. |
error | (error: Error) => ReactNode | - | Error renderer. If not provided, the error is thrown for an error boundary. |
onReady | () => void | - | Callback when the client is ready. |
onError | (error: Error) => void | - | Callback when initialization fails. |
On mount:
client.start().loading while starting.SyncProvider.error or throws to an error boundary.Defer client creation until mount:
<NextSyncProvider
client={() =>
createSyncClient({
/* ... */
})
}
loading={<Spinner />}
>
{children}
</NextSyncProvider>Useful when configuration depends on browser-only values (cookies, localStorage).
Decode snapshots serialized on the server. See Server utilities for the serialization side.
Decodes a JSON-encoded bootstrap snapshot string.
import { decodeBootstrapSnapshot } from "@stratasync/next";
const snapshot = await decodeBootstrapSnapshot(encodedString);Signature: decodeBootstrapSnapshot(encoded: string): Promise<BootstrapSnapshot>
Deserializes a BootstrapSnapshotPayload object. Handles both JSON and gzip-base64 encodings.
import { deserializeBootstrapSnapshot } from "@stratasync/next";
const snapshot = await deserializeBootstrapSnapshot(payload);Signature: deserializeBootstrapSnapshot(payload: BootstrapSnapshotPayload): Promise<BootstrapSnapshot>
Checks if a bootstrap snapshot is too old to use. Default maxAge is 30,000ms (30 seconds).
import { isBootstrapSnapshotStale } from "@stratasync/next";
const isStale = isBootstrapSnapshotStale(snapshot, 30_000);Signature: isBootstrapSnapshotStale(snapshot: BootstrapSnapshot, maxAge?: number): boolean
Pre-populates IndexedDB from a bootstrap snapshot so the client can skip network bootstrap.
import { seedStorageFromBootstrap } from "@stratasync/next";
import { createIndexedDbStorage } from "@stratasync/storage-idb";
const result = await seedStorageFromBootstrap({
storage: createIndexedDbStorage(),
snapshot: bootstrapSnapshot,
dbName: "my-app-sync",
clearExisting: true,
validateSchemaHash: true,
batchSize: 500,
closeAfter: true,
});
if (result.applied) {
console.log(`Seeded ${result.rowCount} rows`);
} else {
console.log(`Skipped: ${result.reason}`);
}SeedStorageOptions:
| Option | Type | Default | Description |
|---|---|---|---|
storage | StorageAdapter | Required | Storage adapter instance. |
snapshot | BootstrapSnapshot | BootstrapSnapshotPayload | string | Required | The bootstrap data to seed. |
dbName | string | "sync-db" | Database name. |
clearExisting | boolean | true | Clear storage before seeding. |
validateSchemaHash | boolean | true | Validate schema hash matches. |
batchSize | number | 500 | Number of rows per write batch. |
closeAfter | boolean | true | Close storage after seeding. |
schema | SchemaDefinition | ModelRegistrySnapshot | - | Schema for hash validation. |
SeedStorageResult:
| Field | Type | Description |
|---|---|---|
applied | boolean | Whether the seed was applied. |
rowCount | number | Number of rows seeded. |
reason | "schema_mismatch" | undefined | Reason if not applied. |
Checks if prefetched data is too old to use.
import { isPrefetchStale } from "@stratasync/next";
const isStale = isPrefetchStale(prefetchedData, 30_000);Signature: isPrefetchStale(prefetched: PrefetchedData, maxAge?: number): boolean
Import hooks directly from @stratasync/next in client components:
"use client";
import { useModel, useQuery, useConnectionState } from "@stratasync/next";Note:
useModelStateis not re-exported from@stratasync/next. Import it directly from@stratasync/reactif you need it:import { useModelState } from "@stratasync/react";