React Native
Offline-first React Native, the way it should ship.
June 11, 2026 · 18 min read
Most application architecture diagrams quietly assume that the network is reliable. There is an arrow from the phone to the API, and the arrow always works.
Field software exposes how fragile that assumption is. When a field officer is collecting data several kilometres from reliable connectivity, a request timeout is not a temporary inconvenience. It can mean a lost form, duplicate work, or an operator who quietly stops trusting the application and goes back to paper. The same is true, in smaller ways, for anyone moving between cell towers during an LTE handover: the network is not absent, it is inconsistent — which is harder to design for.
Offline-first is not "supporting offline mode". It means designing the application so that the local device remains useful and authoritative even when connectivity disappears. This piece is what I would tell a team starting that journey, based on shipping offline-capable software to more than 100K users.
The real problem
Teams rarely fail at offline-first because they chose the wrong library. They fail because they designed an online-first product and tried to add offline behaviour afterwards, usually as a cache. The symptoms are familiar: offline is treated as an exceptional state with its own screens, UI state is bound directly to API responses, every request is assumed to eventually succeed, and conflict resolution is postponed until the first production bug report makes it unavoidable.
The underlying mistake is treating synchronization as a networking problem. It is a data consistency problem. The question is not "how do I retry this request?" but "which copy of this record is true, and when?"
That one change ripples through almost every downstream decision: how screens load, how errors are expressed, how IDs are generated, how schemas evolve, and what the backend has to promise about accepting late, repeated or out-of-order writes.
What changes when offline is a real requirement
Once offline stops being a nice-to-have and becomes an operating requirement, the list of consequences gets concrete quickly. Screens must render from local state, not from a spinner waiting on a request. Writes must succeed without the server. Synchronization becomes a background process with its own lifecycle, rather than something that happens inside a button handler.
Errors change shape too. "Request failed" is no longer a meaningful message, because the user's action did not fail — it was saved, and the delivery is pending. The user needs to understand sync state without learning what a queue is. Retries must be safe, duplicate mutations must be impossible rather than unlikely, and schema migrations become significantly more important, because some devices will run old code against old data for weeks.
None of this is exotic. But it is a different mental model, and it needs to be agreed on before the first feature is built, not after.
Choosing a local store
React Native gives you three serious options. Choose by data shape and ownership.
MMKV is excellent for preferences, tokens, feature flags and lightweight local state. It is fast and simple, and it is the wrong place for anything with relationships.
SQLite (op-sqlite or expo-sqlite) is the better default when the device needs to own domain data. It is relational, transactional, well understood, and comfortably handles the tens of thousands of rows most field apps need.
WatermelonDB earns its place when you need a reactive database abstraction over large local datasets — lazy loading, observable queries, and a sync protocol you implement against your own backend.
Do not confuse persistence with architecture
Choosing SQLite does not make an application offline-first, in the same way that choosing Postgres does not make a backend reliable. The architecture still needs a local source of truth, a durable mutation queue, synchronization, safe retries, a conflict policy and a migration strategy. The database is the easy part.
Sync engines: ElectricSQL, PowerSync, WatermelonDB Sync
Rolling your own sync is an expensive way to learn distributed systems. There are production-ready options, and each carries assumptions worth understanding.
ElectricSQL assumes Postgres is the centre of your world. Data flows from Postgres into local stores via "shapes", which keeps the mental model close to the database you already operate. The developer experience is good when your domain maps cleanly onto tables; it becomes awkward when your write path needs heavy business logic that does not live in the database, because you still own how writes get back to the server.
PowerSync streams Postgres changes into local SQLite using sync rules that partition data per user or tenant, and uploads writes through your own backend. That makes it strong when fine-grained partitioning matters and you want server-side validation on every write. The cost is another service in the operational footprint, and sync rules that need the same care as an authorization model.
WatermelonDB Sync is a pull/push protocol you implement against any backend. You get the most control over conflict handling and data shape, and you pay for it in engineering time and in bugs you will write yourself.
| Situation | Likely direction |
|---|---|
| Backend is already Postgres | ElectricSQL / PowerSync |
| Highly custom backend | WatermelonDB Sync / custom protocol |
| Fine-grained data partitioning | PowerSync |
| Strong Postgres-centric architecture | ElectricSQL |
There is no universal winner. The right question is which set of trade-offs your team can operate for years, not which demo looked best.
The architecture I would start with
The UI knows nothing about the network. It reads from repositories and re-renders when local data changes. The repository layer holds domain rules and hides which store a query uses. SQLite owns the data the user sees. The outbox records what the user intended, durably. The sync worker is the only component that talks to the server, and the server is responsible for validating and deduplicating what arrives.
Each boundary exists so that one kind of change — a new screen, a new entity, a new sync engine — does not force a rewrite of the others.
Designing the write path
The write path is where naive offline apps fall apart. The version that holds up:
- Commit the user's intent locally, in a transaction.
- Update the UI from the local database, not from a response.
- Persist the mutation in an outbox in the same transaction.
- Synchronize when connectivity allows.
- Retry safely, with exponential backoff and jitter.
- Acknowledge or reconcile the mutation.
- Update local state from server truth where the server is authoritative.
Idempotency is what makes step five safe. A POST that times out may have succeeded; retrying it blindly creates a duplicate record. The fix is to make every mutation identifiable: generate the entity ID on the client, give each mutation its own ID, and have the server treat a repeated mutation ID as "already applied".
// outbox row, written in the same transaction as the domain change
{
mutation_id: "c8f1…", // idempotency key
entity: "visit",
entity_id: "0f3a…", // client-generated UUID
op: "create",
payload: { … },
attempts: 0,
created_at: 1718100000000
}Use NetInfo to wake the worker, not to gate the UI. The UI should not need to know whether the network is up.
Sync state is product UX
Synchronization is not purely infrastructure. The moment a write can be pending, the product has to communicate that honestly. The useful states are few: saved locally, syncing, synced, waiting for connection, needs attention, conflict detected.
In practice that becomes small, calm copy: "Saved on device". "Syncing…". "Last synced 4 minutes ago". A badge on the record that needs attention, rather than a modal that blocks the next task.
Conflict resolution is a business rule
Last-write-wins is fine for user preferences. Counters should merge deltas, not overwrite totals. Inventory needs domain-aware reconciliation. Financial transactions should not rely on simplistic client-side resolution at all — the server decides. Operational workflows often benefit from state-machine rules, where the more advanced state wins and invalid transitions are rejected.
The correct conflict strategy is a business rule disguised as an engineering rule.
That is why engineers should not choose it alone. Write the policy down per entity, agree it with whoever owns the business process, and treat changes to it as seriously as changes to pricing. CRDTs and operational transforms are useful tools, but they answer "how do we converge?", not "what should the answer be?".
Background sync on real phones
Both iOS and Android restrict background execution to protect battery and data, and the rules differ by platform, OS version and device manufacturer. Apps get terminated, restarted, and suspended mid-request. Networks appear and vanish. A thousand devices reconnecting at once after an outage can produce a retry storm that looks a lot like an attack.
Treat stale queues as a first-class case too. A mutation that has waited nine days might still be valid, or it might reference a record that no longer exists. Decide what happens before it happens.
The cost of offline-first
Offline-first increases implementation complexity, testing effort, observability requirements, migration complexity and support load. Engineering estimates grow, and they should.
What it can buy is less operational disruption, fewer failed field workflows, less duplicate work, and a product that does not depend on conditions the user cannot control. Whether that trade is worth it depends on who uses the software and where. For a dashboard used in an office, probably not. For software that people depend on in the field, often yes.
It is a business decision as much as an architecture decision, and should be made as one.
Offline systems need better observability
In an online system, failures show up as errors on your server. In an offline system, failures sit silently on devices. Without deliberate signals, a team cannot tell whether sync is healthy. The metrics I would want from day one:
| Signal | What it tells you |
|---|---|
| Queue depth | How much work is waiting on devices |
| Oldest mutation age | Whether anything is stuck |
| Sync success rate | Overall health of the pipeline |
| Retry count | Flaky paths and retry storms |
| Conflict frequency | Whether the conflict policy fits reality |
| Sync latency | Time from local write to server ack |
| Failed mutations | Writes that will never apply without help |
| Client/server divergence | Records that disagree after sync |
Test the failure, not the happy path
Detox or Maestro flows that toggle connectivity mid-action are the baseline. A debug "chaos mode" that drops a share of requests and responses is cheap and humbling. Beyond that, the scenarios worth writing tests for are the uncomfortable ones:
- connectivity disappears during a write;
- the app is force-quit immediately after a local transaction;
- the device stays offline for several days;
- the server changes the same data while the device is offline;
- the same record is edited on two devices;
- authentication expires while mutations are queued;
- the schema changes while clients are offline;
- the user taps submit five times;
- device storage is nearly full.
Offline systems are defined by how they behave when things go wrong. Test that.
What I would not do
I would not make the network the source of truth for every screen. I would not scatter sync logic across React components, where it becomes impossible to reason about. I would not retry mutations without idempotency, build a custom sync protocol before proving the need, or use MMKV as a relational store because it was already installed.
And I would not postpone conflict resolution until launch, or hide synchronization errors from users and operators to keep the UI tidy. Hidden failures do not go away; they turn into support tickets and lost trust.
Offline-first is also a team problem
The hardest parts of offline-first sit between teams. Mobile and backend engineers need shared ownership of the sync contract: what the server accepts, how it rejects, how it deduplicates, and what "applied" means. Conflict policies need to be documented per entity. Failure semantics need to be agreed, not discovered.
"Done" has to mean more than the happy path works on office Wi-Fi. And sync should be reusable infrastructure, not something every feature team solves again in its own slightly different way.
Good architecture here is mostly about cognitive load. When the boundaries are right, an engineer adding a new entity writes a repository, a schema and a conflict rule — and does not have to think about the network at all.
Closing thought
Offline-first is not primarily about surviving airplane mode. It is about building software that remains trustworthy when the environment around it is unreliable.
That means local state is intentional, synchronization is explicit, conflicts have rules, and the user is never punished for conditions they cannot control.
I build and lead teams around systems where reliability matters. If you're designing an offline workflow, evaluating an architecture, or untangling a queue that has become part of your product, I'm happy to compare notes.
More writing
- React Native Architecture Decisions That Become Expensive Later
React Native · 7 min read
- Why Good Engineers Care About Failure Modes
Distributed Systems · 5 min read
- What Engineering Managers Should Actually Measure
Engineering Management · 6 min read