@sqlite-sync/core

Core sync engine for sqlite-sync — a local-first SQLite sync engine for web apps, with reactive queries, offline persistence, and CRDT-based replication.

This package provides:

• createSyncedDb() for client orchestration (worker attach, snapshot hydration, sync state).
• Declarative synced tables (defineSyncSchema, t.table) and migrations (createMigrations).
• Live query primitives (db.createLiveQuery(...)), typed through Kysely.
• CRDT primitives with Last-Write-Wins per-field replication and HLC timestamps.
• The worker runtime (@sqlite-sync/core/worker) and server protocol types (@sqlite-sync/core/server).

Install

pnpm add @sqlite-sync/core kysely

For React bindings, add @sqlite-sync/react.

Quick start

import { createMigrations, createSyncedDb, defineSyncSchema, t } from "@sqlite-sync/core";

const migrations = createMigrations((b) => ({
  0: [
    b.createTable("_todo", (table) =>
      table
        .addColumn("id", "text", (col) => col.primaryKey().notNull())
        .addColumn("title", "text", (col) => col.notNull())
        .addColumn("completed", "boolean", (col) => col.notNull().defaultTo(false))
        .addColumn("tombstone", "boolean", (col) => col.notNull().defaultTo(false)),
    ),
  ],
}));

// Queryable as "todo", stored in "_todo". `id` and `tombstone` are added automatically.
export const syncDbSchema = defineSyncSchema({
  tables: {
    todo: t.table({
      title: t.text(),
      completed: t.boolean().default(false),
    }),
  },
  migrations,
});

export type Todo = typeof syncDbSchema.tables.todo.$row;

const worker = new Worker(new URL("./db-worker.ts", import.meta.url), { type: "module" });

export const db = await createSyncedDb({ dbId: "app-db", worker, syncDbSchema });

Start the worker (remote sync optional):

// db-worker.ts
import { startDbWorker } from "@sqlite-sync/core/worker";
import { syncDbSchema } from "./db-schema";

await startDbWorker({ syncDbSchema });

Requirements

• Browser: Web Workers + Web Locks + an OPFS-capable SQLite WASM environment.
• Peer dependency: kysely (^0.28.0 || ^0.29.0).

Documentation

See the full documentation and the project README for guides, recovery/storage versioning, and the Cloudflare sync backend.

License

MIT