Offline First

---
name: offline-first
description: Offline-first — local storage schema, sync queue, conflict resolution.
---

## Storage Structure

- Define a clear schema for the local store (IndexedDB, SQLite via OPFS, etc.) — treat it as a real database with versioned migrations
- Mirror the API shape when practical; document intentional divergences in code comments
- Never store sensitive data (tokens, PII) in unencrypted client storage

## Sync Strategy

- Implement a sync queue: operations made offline are queued and replayed when connectivity is restored
- Use timestamps or vector clocks for conflict resolution — define a clear policy (last-write-wins, server-wins, or manual merge) and document it
- Handle partial sync failures: operations must be atomic or rollback-safe; a failed sync must not leave local state inconsistent
- Expose sync status to the user — they must know whether data is saved locally only or confirmed on the server

## Connectivity Detection

- Combine `navigator.onLine` with an actual fetch probe to a known endpoint — `navigator.onLine` alone is unreliable (returns `true` on captive portals and metered connections)
- React to `online`/`offline` browser events to trigger sync and update UI state accordingly
- Show clear offline indicators — never silently queue operations without informing the user