@karpo.dev/sdk-web

The Karpo client for browsers. It runs the SDK core and SQLite WASM in a dedicated worker, persists the replica to OPFS, and keeps queries live: reads hit local SQLite, writes land locally first and sync in the background.

npm install @karpo.dev/sdk-web

Usage

import { createKarpoClient } from "@karpo.dev/sdk-web";
import schema from "./karpo/generated/schema.json";

const karpo = await createKarpoClient({
  schema,
  user: "u01",
  target: "dev",          // or gatewayUrl for a backend the SDK has no name for
  publishableKey: "pk_…", // engages the auth surface
});

// One read-only statement; anything that is not a single SELECT is rejected.
const rows = await karpo.runtime.selectSql("select * from todos order by title", []);

await karpo.runtime.insert("workspaces", "todos", {
  containerId: "ws-demo",
  title: "Write the README",
});

Most apps do not call this directly — karpo generate emits a karpo.ts that wraps it as initKarpo() and exposes a typed db.

What the package handles for you

• Multi-tab. By default one tab is elected leader and owns the replica, the poke socket, and the token-refresh timer; the others route their SQL to it and are promoted when it goes away. That is what makes the device identity a property of the browser profile rather than of the window. multiTab: "per-tab" gives every tab its own device and replica.
• Fallback. Where a worker or OPFS is unavailable the same core runs on the main thread over sqlite-wasm's localStorage VFS. Behavior is identical; persistence is not, so the fallback is logged at error level.
• The inspector. In a dev build the devtools agent is installed automatically, and @karpo.dev/devtools serves the UI at /__karpo.

Vite must not pre-bundle the workers, or new URL("./worker.js", import.meta.url) resolves next to the bundle instead of next to the package:

optimizeDeps: { exclude: ["@sqlite.org/sqlite-wasm", "@karpo.dev/sdk-web"] }

Without it the app still runs — it quietly falls back to the main thread and loses OPFS persistence, which is a bad thing to discover later.

Docs: https://karpo.dev/web and https://karpo.dev/database. Source: https://github.com/Chirich-GmbH/karpo-core (packages/sdk-web).