TL;DR — Offline-first is local-first plus a disciplined sync layer. The user always writes locally; sync runs in the background; conflicts are resolved with a documented policy. Optimistic UI hides the network entirely on the happy path.
“Offline support” is often bolted on as a feature. “Offline-first” is an architecture choice. The difference shows up in every interaction — when offline-first is done right, the user does not know whether they were online or not.
The four layers
1. Local database as source of truth
SQLite is the default. WatermelonDB or PowerSync on top for sync ergonomics. The UI reads from local; never from the network directly.
2. Sync queue
Every local mutation is also written to a sync queue: type, payload, timestamp, retry count. A background worker drains the queue against the server when connectivity returns. Idempotent operations are essential.
3. Conflict resolution policy
Last-write-wins is simplest and wrong for most data. CRDTs are correct and complex. The middle ground: per-resource policies — “user profile is last-write-wins, notes are merged at field level, transactions are server-authoritative”.
4. Optimistic UI
Local writes apply immediately. The UI shows the new state. If sync fails permanently, the user is told — but not while they are still typing. This is the part that makes offline-first feel native instead of “loading”.
What we got wrong early
- Mixing online and offline reads — pick one, route everything through it
- Treating the sync queue as a queue (FIFO) instead of as a graph (some operations depend on others completing first)
- Trying to resolve all conflicts client-side — server-side authoritative resolution for high-stakes data, client-side for low-stakes
- Skipping the “stuck queue” UX — the user has to be able to see what failed and retry
Frequently asked questions
Do all mobile apps need offline support?
No. Apps that are pure interfaces over server-side state (e.g., admin tools) can stay online-only. Anything where the user expects continuity across connectivity (notes, tasks, drafts) needs offline-first design.
Which database for local storage?
SQLite (or WatermelonDB on top of it) for relational; MMKV for key-value; RealmDB if you want a sync engine bundled. Avoid AsyncStorage for anything past trivial state.
Working on something similar?
T-Square architects, builds and operates production systems for learning, AI and custom software products. Talk to a senior engineer for a second opinion.