Offline-first data

​

Storage per platform

​

Files

​

How data moves

page ─► store.load() ─► repo.list() ─► SQLite (instant) ─► render
                    └─► sync in the background (never blocks the UI)
store.add / update / remove ─► repo write (row → sync_state='pending') ─► scheduleSync() (debounced)
sync(): push pending (PUT upsert · DELETE tombstone) ─► pull the list (GET) ─► merge (last-write-wins)
app resume · sign-in ─► syncAll() ─► every registered store syncs and refreshes its list

• sync_state is 'pending' for a local change not yet pushed and 'synced' once it matches the server.
• deleted_at is a tombstone. The UI hides the row, and the row stays until the server confirms the DELETE. Then it is removed.

​

Sync rules

• When it runs: after the page’s store.load() reads local data, after every local write (debounced, 800 ms by default), on the browser’s online event, when the app returns to the foreground, right after sign-in, and on syncNow().
• When it doesn’t: while signed out, while offline (navigator.onLine === false), or when the signed-in account doesn’t own the database. The cache is left alone.
• One run at a time: a sync requested during a run is folded into a single follow-up run.
• Push first, oldest change first. A live row goes out as PUT /v1/<resource>/:id and is then marked synced. A tombstone goes out as DELETE /v1/<resource>/:id and is then removed locally; a DELETE answered 404 or 410 counts as done. The first transient failure (network error, timeout, 5xx, 429) ends the run: the remaining changes stay pending, nothing is pulled, and the next trigger retries.
• A rejected change doesn’t block the rest. If the server refuses a change outright (a 4xx other than 401, 408, 426 and 429, such as a validation error or a conflict), the change stays pending and the push moves on to the next one, then pulls as usual. The rejection is reported once per change and session as an Error: console in development, Sentry in production. The change goes out again on later syncs, so an edit or a server fix can still push it.
• Then pull the full list with GET /v1/<resource>. If the pull fails, nothing is applied, so a network error can never empty the cache.
• Merge, last-write-wins by updatedAt: a server row overwrites the local row, unless the local row is still pending and at least as new. A tie keeps the local edit. A synced local row that is missing from the server’s list was deleted on another device, so it is removed.

​

Sign-out and session expiry

​

Add your own entity

​

Server contract

• The primary key is a text column holding the client’s id, not a server-generated id, so a record keeps the same id on every device.
• user_id is a foreign key with ON DELETE CASCADE.
• Run npm run db:generate afterwards.

​

The Notes example

​

Remove the Notes example

​

Gotchas

1. jeep-sqlite under Vite: sqlite.ts loads the custom-elements build (jeep-sqlite/dist/components/jeep-sqlite + defineCustomElement()), not jeep-sqlite/loader. The lazy loader never finishes hydrating, so getDb() hangs on web.
2. The wasm file must match sql.js: public/assets/sql-wasm.wasm must come from the exact sql.js version in package.json (1.11.0). When you upgrade sql.js, copy its dist/sql-wasm.wasm over it. A mismatch breaks only web and desktop, so native testing won’t catch it.
3. persist() after every write: on web, a write stays in memory until it is saved to IndexedDB. The repo factory does this for you; do the same in any raw SQL you add.
4. One write at a time: every write shares one connection, and each db.run() opens its own transaction. Two writes that overlap fail on web and desktop (“cannot start a transaction within a transaction”), and the losing write is dropped. The repo factory runs each write method through serializeWrite(). Wrap any raw SQL write you add the same way, including the reads that decide it and its persist(). Don’t call a queued function from inside serializeWrite(): the queue isn’t reentrant, so the call would wait forever. If it happens anyway, the queue reports any write that waited more than 10 seconds for its turn. The report is an Error, so you see it in the console in development and in Sentry in production, instead of a silent hang.
5. list() throws when signed out: a sign-out that races a sync must not feed an empty list into the merge and wipe the cache.
6. Migrations only grow, and their numbers are global: never edit a shipped step; add a new one with a higher version. Version numbers are unique across all entities, and a collision throws at startup.
7. A tie keeps the local edit (>= in the merge). This is intentional; don’t tighten it to >.
8. Unit tests: npm test (Vitest, TZ=UTC) runs the *.test.ts files next to the code. Tests ship for the offline layer (registry, write queue, cache ownership, sync gate), for token refresh, and for the Pro gate.

​

Gate it behind Pro

const { ensureUnderLimit } = useProGate();

async function onAdd(title: string): Promise<void> {
    if (!ensureUnderLimit(store.items.length, 20)) return; // upsell shown, create blocked
    await store.add({ title, body: '' });
}