Skip to content

Local First

github-actions[bot] edited this page Nov 21, 2026 · 1 revision

Local-first apps with spotkit

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.

The pattern

Sokobanko is the worked example.

  1. A local store. Keep the app's data in TanStack DB collections (@tanstack/db), filled from the server with @tanstack/query-db-collection and kept in the browser.
  2. Write locally first. A change is applied to the collection at once (an optimistic mutation), so the screen updates with no wait.
  3. A durable outbox. The change becomes a transaction in @tanstack/offline-transactions, stored in IndexedDB, so it survives reloads and being offline.
  4. 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.
  5. 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.
  6. 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 with deleteMe(), then localData().clear(), which removes the outbox too, so nothing uploads again.
  7. 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.

What isn't covered yet

  • 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.

Clone this wiki locally