Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 37 ยท State and Storage

Offline First and Sync

Design Ionic apps that work without a connection: local-first writes, an outbox queue with retries, idempotent requests, conflict resolution and a clear sync status.

Phones lose signal in elevators, tunnels and airplane mode. An app that shows a spinner or an error without a connection feels broken, while one that keeps working feels reliable. Offline first means the app treats the local database as the primary place for data and the server as a copy to synchronize with.

This lesson gives you the architecture and the building blocks: reading from a cache, writing through an outbox queue, retrying safely and resolving conflicts. It assumes you know how to detect connectivity (see Geolocation, Device and Network) and where to keep data (Storage, Preferences and SQLite).

The architecture

flowchart LR
  UI["Pages and components"] <--> L[("Local database")]
  L --> O["Outbox queue<br/>(pending changes)"]
  O -->|"when online"| S["Server API"]
  S -->|"pull changes"| L

The UI never talks to the server directly. It reads and writes locally, and a sync service moves changes both ways.

Benefits: instant screens, no empty states while loading, and the same behavior online and offline. The cost is more code: you must handle duplicates, ordering and conflicts.

Read strategies

  • Cache first: show local data immediately, refresh in the background, update the screen when new data arrives. Best for lists.
  • Network first with fallback: try the server, fall back to local data on failure. Best for data that must be fresh.
  • Stale while revalidate: show cached data, mark it with the time of last sync.

Always show users what they are looking at: a small "Updated 5 min ago" or an "Offline" chip prevents confusion.

Write strategy: the outbox

When the user saves a note offline, you do not send a request. You write it to the local database and append an operation to an outbox. A sync loop sends the outbox in order when the connection returns. Each operation needs:

  • a client-generated id (a UUID), so the server can recognise duplicates;
  • a type (create, update, delete) and payload;
  • a retry count and a timestamp.

Because a request can succeed on the server while the response is lost, the app may send the same operation twice. The server must treat the operation id as an idempotency key: the second time, it returns the stored result instead of creating a duplicate.

JS An outbox with retries and idempotency

Press Run (or Ctrl + Enter) to see the console output here.

No output.

In production, retries wait longer each time (exponential backoff: 1 s, 2 s, 4 s, with a little randomness), and the outbox lives in SQLite, so pending work survives an app restart.

Conflicts

Two devices edit the same note while offline. When both sync, the server holds two versions. Strategies, from simplest to richest:

  1. Last write wins by timestamp. Simple, but silently discards someone's work, and device clocks are not trustworthy.
  2. Version numbers: each record has a version. A client sends the version it started from; the server rejects the write if it has moved on, and the client must merge or ask.
  3. Field-level merge: merge changes per field so editing the title on one device and the body on another keeps both.
  4. CRDTs: data structures that merge automatically, used for collaborative text. Powerful, and more complex than most apps need.
JS Version checks and field-level merge

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Showing sync status

Users need to see state without being nagged:

  • a subtle "Offline" or "Syncing" indicator in the header;
  • a "pending" mark on items not yet sent;
  • an explicit message only when data needs attention (a conflict, a rejected write).

For background work, remember that mobile systems limit what an app can do when closed. The Capacitor Background Runner plugin or platform tasks can wake the app briefly, but you should design as if sync only happens while the app is open.

Test offline behavior on purpose: turn on airplane mode, use Chrome DevTools "Offline" throttling for the web build, and add a debug switch in your app that makes the fake API fail so you can see the outbox work.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In an offline-first app, where does the UI read and write?

    The local store is primary; a sync service moves changes to and from the server.
  2. 2. Why does each outbox operation carry a client-generated id?

    Lost responses cause retries, and the id acts as an idempotency key.
  3. 3. What is the main risk of last-write-wins?

    The later timestamp overwrites the earlier edit, even if it touched different fields.
  4. 4. What does exponential backoff mean?

    Increasing waits avoid hammering a struggling server and save battery.

Summary

  • Offline first: read and write locally, sync in the background.
  • An outbox holds pending operations in order; ids make retries safe.
  • Retry with exponential backoff and keep the outbox persistent.
  • Resolve conflicts with versions and field merges rather than silent overwrites.
  • Show sync status clearly and test offline deliberately.

Next: Unit Testing Ionic Components