On this page
Tracks

Frontend System Design — Offline-First App

Last reviewed 14 Oct 2026

Part of the system design series. Uses the frontend framework. Conflict resolution connects to Collaborative Document Editing.

1. Requirements

Example: a notes/tasks app, or a field app used by delivery agents or sales reps in areas with poor connectivity.

Functional

  • App opens and works with no network: view, create, edit, delete.
  • Changes sync automatically when back online; changes from other devices appear.
  • User can see what’s not yet synced.

Non-functional

  • Never lose a user’s change, including across app restarts and crashes.
  • Fast: reads come from the device, not the network.
  • Handle conflicts when the same item was edited on two devices offline.
  • Works within browser storage limits; app updates don’t break stored data.

2. Key design decision — local data is the source of truth for the UI

Online-first apps fetch, then render, and fail offline. Offline-first apps render from a local database, write to it first, and sync with the server in the background. The network becomes an optimization, not a dependency.

flowchart LR
UI[UI components] -->|read, write| LDB[(IndexedDB<br/>entities + mutation queue)]
LDB -->|live queries| UI
SYNC[Sync engine] --> LDB
SYNC -->|push queued mutations| API[Server API]
API -->|pull changes since cursor| SYNC
SW[Service worker<br/>app shell + asset cache] -.->|serves HTML, JS, CSS offline| UI
UI reads and writes locally; a sync engine moves changes in both directions

Two separate caches, often confused:

  • Service worker cache (Cache Storage) — the app shell and static assets, so the app loads offline.
  • IndexedDB — the user’s data and the pending mutation queue, so the app works offline.

3. Service worker caching strategies

StrategyHowUse for
Cache firstServe from cache, fall back to networkVersioned static assets (hashed JS/CSS, fonts, icons)
Network firstTry network, fall back to cache on failureHTML / app shell when freshness matters
Stale-while-revalidateServe cache immediately, update cache in backgroundAvatars, non-critical API reads
Network onlyNever cacheAuth, payments, anything sensitive

Updates: a new service worker installs in the background and waits; show “New version available — Reload” rather than forcing skipWaiting, which can mix old pages with new assets. Version local DB schemas and migrate on startup.

4. Deep dive — the mutation queue and sync

Writes: apply the change to the local entity and append a mutation record in one IndexedDB transaction:

type Mutation = {
id: string; // client-generated, used as idempotency key on the server
entity: 'task';
entityId: string; // client-generated UUID, so new items have ids offline
op: 'create' | 'update' | 'delete';
patch: Record<string, unknown>;
baseVersion: number; // server version this edit was based on
createdAt: number;
};

Push: when online, send queued mutations in order, batching where possible; the server applies them idempotently by mutation id and returns new versions; remove each from the queue after acknowledgement. Retry with backoff on failure; stop and surface errors for permanent rejections (validation, permission).

Pull: request changes since the last sync cursor (GET /changes?since=...), apply them locally, and advance the cursor. Deletes come through as tombstones.

Triggers: on app start, on the online event, periodically while open, and via Background Sync where supported (it’s Chromium-only, so always keep the in-app triggers).

5. Deep dive — conflicts

The same task was edited on the laptop and the phone while both were offline.

ApproachHowFits
Last-write-wins (per record)Higher timestamp/version winsLow-stakes data; simplest; loses one edit
Field-level mergeMerge non-overlapping field changes; LWW per fieldForms, tasks (title edited here, due date there)
Server rejects, user resolvesServer detects baseVersion mismatch, client shows both versionsHigh-stakes data (orders, records)
CRDTs (Yjs, Automerge)Data types that merge automatically and deterministicallyRich text, collaborative lists

Detect conflicts with versions, not timestamps alone — device clocks are wrong. For most apps, field-level merge with LWW per field plus a visible “edited on another device” notice is the pragmatic answer.

6. Storage and edge cases

  • Quotas: browsers allow sizable storage but can evict it under pressure. Call navigator.storage.persist() to request persistent storage, show usage via navigator.storage.estimate(), and keep large media optional/evictable.
  • iOS Safari may clear script-writable storage for sites not used for a while unless installed to the home screen — tell users to install the PWA for critical offline use.
  • Auth expiry offline: keep working locally; queue mutations; re-authenticate before pushing.
  • Sync status UI: per-item “pending” marker, global “All changes saved” / “3 changes waiting to sync” / “Offline”.
  • Large initial sync: paginate the first pull; let the user work on what’s already downloaded.
  • Logout on a shared device: clear IndexedDB and caches.

7. What real tools exist

  • Workbox (Google) — service worker routing and caching strategies.
  • Dexie (IndexedDB wrapper with live queries), RxDB, PouchDB/CouchDB (built-in replication).
  • Sync engines and local-first stacks such as Replicache, ElectricSQL, PowerSync, and CRDT libraries Yjs and Automerge.

Interview follow-ups

  • “Service worker cache or IndexedDB?” — Service worker cache for the app shell and assets; IndexedDB for user data and the mutation queue.
  • “User edits offline then closes the browser.” — The change and its mutation were written to IndexedDB in one transaction; sync resumes next launch.
  • “Two devices edit the same item offline.” — Detect via base version; field-level merge or user resolution; CRDTs for rich text.
  • “How does the server avoid applying a mutation twice?” — Idempotency by mutation id.
  • “How do you ship an update without breaking offline users?” — Waiting service worker with a reload prompt; versioned DB migrations.

Further reading: web.dev “Offline Cookbook” and the Workbox documentation · MDN documentation on IndexedDB, Storage API (persist, estimate) and Background Sync · Kleppmann et al., “Local-first software” (Ink & Switch, 2019).