Offline-first & optimistic UI

A building-inspection company equips its inspectors with a web app: a checklist of about 40 items per building, each marked pass or fail, with notes and photos. Noor starts the day's first inspection in a parking garage two levels underground. The app shows a spinner, then "Network error", and the first three answers are gone.

The app was built online-first: every screen fetched from the server and every tap was a request that had to succeed before the screen changed. An offline-first app turns that around. The device keeps its own copy of the data the user needs; the interface reads and writes that copy, and a sync process exchanges changes with the server whenever it can:

The goal has a well-known statement in the local-first software movement: no spinners, and the network is optional. The device's copy is where the user works, and servers hold copies that let other devices and people see the same data. Some backends build it in; Firestore, for example, keeps an offline cache on Android and Apple devices by default, though on the web it has to be turned on.

The offline-first inspection app has three local pieces and one remote one. The app's code and assets are cached on the device, so it opens with no signal. Inspection data lives in a local database. Every change also goes into an outbox, a local queue of changes not yet confirmed by the server:

In a browser, a service worker sits between the page and the network like a proxy, and can answer requests from its own cache; that's what lets the app shell load in the garage. The data goes in IndexedDB; a native app can use an on-device database such as SQLite.

Don't decide whether to sync by asking the browser if it's online. navigator.onLine reports a network connection, not internet access: a device on a local network with no route to the internet still counts as online. The reliable test is to try the request, and treat a timeout like any other failure. The Background Synchronization API can wake a service worker when connectivity returns, but it isn't available in all major browsers, so the app must also retry when it is opened.

Even with a good signal, waiting 300 ms for each checkmark makes a 40-item checklist feel sluggish. An optimistic update shows the expected result immediately and sends the request in the background, on the assumption that it will usually succeed. When it doesn't, the interface has to undo the change and say why:

Client libraries build this pattern in:

• React's useOptimistic shows an optimistic value while an action is pending, and returns to the real value when the action ends.
• TanStack Query saves a snapshot of the cached data before the mutation, restores it on error, and refetches when the request settles either way, so the screen ends up matching the server.
• Firestore notifies listeners of a local write before it reaches the backend, a feature it calls latency compensation, and marks those documents with hasPendingWrites.

That last flag matters for honesty. An optimistic screen should still let the user tell "saved here" from "confirmed by the server": the inspection app shows a small pending badge on items still in the outbox, and a count of unsynced changes in the header. And not every action should be optimistic. The inspection app shows checkmarks and notes at once, but submitting a signed final report waits for the server, because telling a building owner it passed and then retracting it costs more than a second's wait.

Back in the garage, Noor marks 25 items and takes 12 photos before reaching signal at street level. The outbox now holds 37 changes. A retry is certain: the connection may drop halfway, or a response may be lost after the server applied the change. So the replay has rules:

Large files go separately. The 12 photos are uploaded as files in their own resumable queue (Resumable & chunked uploads), and the outbox entry for each item only references the photo's id, so a slow upload doesn't block the small changes behind it.

The server side has one more duty: telling the device what changed while it was away. A common shape is a change feed with a cursor. The device asks for everything after the last position it saw and stores the new position. It's the same idea as Change data capture, scoped to what this user may see.

While Noor is offline, a supervisor at the office edits the same building's "fire door" item from fail to pass with a note. Noor, still in the garage, adds a different note to the same item. Both changes are valid, and both arrive at the server. What happens next depends on a rule chosen in advance:

CouchDB shows the point of the second rule: the losing revisions aren't lost, only hidden, and an application that never looks at them has effectively lost them. Merging by data type is covered in CRDTs: data types that always merge.

Real apps mix rules per field. For the inspection app: notes are lists, so both notes are kept; the pass or fail result uses the server's rule, so a supervisor's decision overrides an inspector's earlier offline answer and the inspector is told; photos never conflict, because each has its own id. Avoid deciding by the device's clock: it is set by the device, not by you, so "latest timestamp wins" can let an older edit win (Time, clocks & ordering).

A native app's database stays until the app is removed. A web app's doesn't have to. By default a browser stores a site's data as best-effort: it lasts while the site is under its quota and the device has space. Under storage pressure, browsers evict whole sites' data, least recently used first. A site can ask for persistent storage with navigator.storage.persist(), which only the user can clear; Firefox asks the user, while Safari and Chromium browsers decide from how the user has used the site.

Safari adds a rule that matters most for offline apps. Its tracking prevention deletes all of a website's script-writable storage, including IndexedDB, local storage and service worker caches, after seven days of Safari use without the user interacting with the site. Web apps added to the home screen keep their own count of days, based on their own use. Private browsing modes usually delete stored data when the session ends.

For the inspection app, the consequences are concrete:

• Sync early and often, so the outbox is rarely more than minutes old.
• Ask for persistent storage, and handle the quota error the browser throws when space runs out.
• Show unsynced work, and warn before the user signs out or clears the app with changes still queued.
• Treat the device copy as a cache plus an outbox, never as the only copy of confirmed data.

For the inspection app, and most apps used where the signal comes and goes:

The cost is real: two copies of the data, a sync protocol, and conflict rules to design and test. It pays off where users work without a reliable connection, or where every interaction waiting on a round trip makes the product feel slow.