Back to projects
Projectadvanced 7 steps ~100 min

Offline-First Notes

Build local-first writes, an outbox with retries and backoff, per-field conflict resolution, and honest sync status.

What you'll build

A notes app that works offline, shows sync status, and merges changes from two devices without losing data.

  • React
  • optimistic UI
  • sync queue
  • backoff
  • conflict resolution
Project briefrequirements and design decisions

Requirements

  • Edits apply instantly, online or offline
  • Changes made offline sync automatically when back online
  • Failed syncs retry with exponential backoff
  • Concurrent edits from two devices resolve the same way everywhere
  • The UI always shows sync state: saved, pending, or offline

Architecture decisions

  • Local store is the source of truth for the UI; the server is a replica
  • Outbox queue of operations instead of syncing whole documents
  • Last-writer-wins per field with timestamps and client ids as tie-breakers
  • Network is simulated so failure cases are testable

Stretch goals

  • Persist the store and outbox to IndexedDB
  • Replace field LWW with a CRDT for note bodies (Yjs)
  • Background sync via a service worker

Production checklist

  • Idempotent server endpoints (operation ids)
  • Storage quota handling and eviction
  • Clock skew handling (server timestamps or hybrid logical clocks)
  • Conflict UI for cases users must resolve

1What we're building

Most apps treat the network as reliable and the local copy as a cache. Offline-first apps flip that: the local store is the source of truth for the UI, and the server is a replica that catches up when it can.

You'll build the sync engine and UI for a notes app:

  1. Local-first writes: edits apply instantly, online or offline.
  2. An outbox: every change becomes a queued operation, sent when online.
  3. Retries with exponential backoff when the server fails.
  4. Deterministic conflict resolution: when two devices edit the same note, every replica ends up with the same result.
  5. Visible sync state: saved, pending, or offline.

The network is simulated, with switchable failures, so you can test the cases that are hard to reproduce on a real connection.

This is how apps like Linear, Notion, and Figma feel instant: the UI never waits for the server.

Offline-First Notes project | Bloom