An app that still opens without Wi-Fi is not automatically an offline-first app.
Caching the shell is the easy part. The harder questions start when someone edits a record on a train, opens the same app in two tabs, loses connectivity halfway through a request, and comes back online after another device has changed the same data.
A useful way to think about offline-first architecture is as five separate jobs:
- Keep the application shell available.
- Persist meaningful user data locally.
- Record writes that have not reached the server.
- Synchronize safely when connectivity returns.
- Coordinate multiple tabs and resolve conflicts.
These seven resources cover the building blocks.
1. Service workers: control the network boundary
MDN's Service Worker API guide is the right starting point for request interception, caching strategies, lifecycle, and offline responses.
A service worker sits between the page and the network. It can serve cached assets, return an offline fallback, or route requests through different strategies.
Use it for: application shell caching, static assets, navigation fallbacks, and network request strategies.
Do not confuse it with: a durable application database. A cached response is not a reliable record of a user's pending edits.
2. IndexedDB: persist structured local data
MDN's IndexedDB guide explains the browser's transactional database for structured client-side data.
This is where local drafts, records, and an outbox of pending mutations can live. Unlike a simple cache, IndexedDB lets you query and update structured records through transactions.
Use it for: drafts, offline forms, locally created records, and pending operations.
Think carefully about schema versioning, transaction boundaries, storage quotas, and what happens when a browser evicts data. If losing an edit would be serious, communicate the persistence state clearly to the user.
3. Background Sync: a retry mechanism, not your only sync path
The Background Synchronization API allows a service worker to retry deferred work when the browser decides connectivity has returned.
There is an important compatibility caveat: MDN marks this API as having limited availability. Browser-managed background execution is not a guarantee that every queued operation will run at an exact time.
Use it as progressive enhancement. Keep a foreground retry path for when the app is open, and show users whether their changes are pending, syncing, or confirmed by the server.
4. Workbox Background Sync: reduce the plumbing
Workbox Background Sync provides a queue abstraction for failed requests and stores queued requests in IndexedDB. It also has a fallback that retries when the service worker starts in browsers without native Background Sync support.
One detail worth reading before shipping: the default plugin reacts to network failures. HTTP responses such as 4xx or 5xx are not automatically equivalent to a thrown network error. If your retry policy should include selected server errors, configure that behavior explicitly.
Use it for: request retry plumbing, not business-level conflict resolution.
5. Dexie: make IndexedDB easier to work with
Dexie's getting-started guide gives you a more ergonomic API over IndexedDB, including schema declarations and framework-specific starting points.
It is a good fit when you want local persistence without building every database operation around the low-level browser API.
Use it for: local-first CRUD, structured drafts, and a clean persistence layer. Evaluate its cloud add-ons separately if you need managed authentication and synchronization.
6. RxDB: study replication and conflict handling
RxDB's replication documentation is useful when the problem is no longer just storing data locally. It describes pushing and pulling document changes, checkpoints, conflict handling, and support for different backend infrastructures.
The important lesson is that synchronization is a data-consistency problem, not merely a network retry problem. Two devices can edit the same record while disconnected. Your product needs a deliberate rule for what happens next.
Use it for: applications with shared records, multiple devices, and more demanding replication requirements. Read the conflict-resolution behavior before adopting any database.
7. Web Locks: coordinate tabs
MDN's Web Locks API guide explains how same-origin tabs and workers can coordinate access to shared resources.
For example, several open tabs may all notice that the network is back. A lock can help ensure that only one tab performs a particular synchronization job at a time.
Use it for: avoiding duplicate work across tabs. It does not replace server-side idempotency or a correct sync protocol.
A practical selection guide
| Requirement | Start with |
|---|---|
| Offline app shell and assets | Service workers |
| Local structured records | IndexedDB or Dexie |
| Retry failed network requests | Workbox Background Sync |
| Shared data across devices | A replication design such as RxDB |
| Prevent duplicate sync loops across tabs | Web Locks |
Before shipping, test at least these cases:
- The user goes offline before submitting a form.
- The network drops after the server receives a write but before the client receives the response.
- The same operation is retried more than once.
- Two devices edit the same record while offline.
- Two tabs try to synchronize at the same time.
- The browser closes before the queue is drained.
Give every write a stable operation ID or idempotency key. Keep pending work until the server acknowledges it. Define conflict behavior explicitly. And never display “synced” just because a request was placed in a queue.
Offline-first is not a checkbox in a PWA checklist. It is a promise about what happens to a user's work when the network, browser, or another device behaves unexpectedly.
What's the hardest offline-sync problem you've had to solve: retries, conflicts, multi-tab coordination, or communicating sync state to users?
I share engineering notes, experiments, and projects here:
Top comments (0)