Repository navigation
Local First
github-actions[bot] edited this page Nov 21, 2026
·
1 revision
Kodentuzo's apps keep their data on the user's device first and sync to the app's server (the ecosystem's local-first page). This is the first stage: the device writes first, the server stays authoritative. spotkit doesn't hold the data; TanStack DB does, and spotkit covers the user's rights over it.
Sokobanko is the worked example.
-
A local store. Keep the app's data in TanStack DB collections (
@tanstack/db), filled from the server with@tanstack/query-db-collectionand kept in the browser. - Write locally first. A change is applied to the collection at once (an optimistic mutation), so the screen updates with no wait.
-
A durable outbox. The change becomes a transaction in
@tanstack/offline-transactions, stored in IndexedDB, so it survives reloads and being offline. - Send it when you can. The outbox calls the app's API, with the pool's session cookie, and retries with backoff: on network errors, on 5xx and 429, and again when the browser comes back online or the tab becomes visible. A 4xx that won't change is given up and rolled back.
-
Let the server decide. The API checks the change (who the user is:
kit.user(request)) and stores it. Its answer replaces the optimistic copy in the collection. -
Your data covers the device. Export the pool's data (
exportMe()), your server's rows, and the browser's (localData().export()) in one file. Delete withdeleteMe(), thenlocalData().clear(), which removes the outbox too, so nothing uploads again. - Show where the data is. Spotstrap's sync status and "stored here" blocks tell the user what is saved on the device and what has reached the server.
- Data following the user to another device without the app's own API: that is the next stage, a sync engine (ElectricSQL) as a Spotcraft service.
- Conflicts between devices: the server's answer wins.
- End-to-end encryption.
Published from docs/. Edit the files there; changes here are overwritten.