Offline-first React Native apps need more than a cache and a network listener. This guide provides a reusable checklist for local storage, connectivity states, retry queues, conflict resolution, and recovery after interrupted writes so your app remains useful when the device or network is unreliable.
Overview
An offline-first app treats the device as a temporary working environment rather than assuming every screen can read from an API. The user can view previously synchronized data, create or edit records locally, and receive clear feedback about what is pending. When connectivity returns, the app synchronizes those changes with the server.
The most important design decision is to separate four concerns:
- Local data: the records and metadata needed to render the app without a request.
- Connectivity: whether the device appears connected, whether the app can reach your backend, and whether synchronization is currently running.
- Pending operations: durable commands that must be retried after a timeout, app restart, or temporary outage.
- Server authority: the response, version, and conflict policy that determine the final state.
A useful data flow looks like this:
User action
|
v
Write local record + append operation to queue
|
v
Render from local store --------------+
| |
Connectivity becomes usable | App restart or screen revisit
| |
v |
Send idempotent operation ------------+
|
v
Server response: accepted, already applied, rejected, or conflict
|
v
Update local record, queue, and sync metadataDo not equate a reported network connection with a working API. A device may be connected to a captive portal, a restricted Wi-Fi network, or a service that is temporarily unavailable. Use connectivity information as a trigger to attempt synchronization, then let request results determine whether synchronization actually succeeded.
Cache strategy comparison
| Strategy | Best fit | Strength | Trade-off |
|---|---|---|---|
| Memory cache | Temporary screen data | Fast and simple | Lost on reload or app termination |
| Key-value storage | Small preferences, tokens, and compact snapshots | Easy to integrate | Awkward for queries, relationships, and large collections |
| Structured local database | Offline lists, relational data, and queued mutations | Supports durable, queryable state | Requires schema and migration discipline |
| File-based document storage | Large serialized documents or exports | Useful for document-shaped data | Partial updates and concurrent writes need careful handling |
Choose storage based on the data model, not only on the fastest setup. A small prototype may begin with key-value storage, while a production workflow involving relationships, pagination, and queued writes usually benefits from a structured local database. Review the current Expo and React Native compatibility of any storage or networking package before standardizing it.
Checklist by scenario
When the app first loads offline
- Open the local store before waiting for a remote request.
- Display the last successful synchronization time when it is available.
- Differentiate an empty account from an account whose data has not been downloaded yet.
- Disable or explain actions that genuinely require server validation.
- Keep navigation and previously available detail screens usable.
The UI should not show an indefinite spinner because the API cannot be reached. Use a local loading state followed by a clear offline or unavailable state. A stale-data label is often more useful than hiding the content.
When a user creates or edits data offline
- Write the intended local change and its operation record as one durable transaction when the storage layer supports transactions.
- Assign a client-generated operation ID that remains unchanged across retries.
- Record the entity ID, operation type, payload, creation time, and the base server version the user edited.
- Render the optimistic result immediately, with a pending marker that is visible but not disruptive.
- Provide an undo or cancel path only if it can be represented safely as another operation.
A queue item should contain enough information to retry without reconstructing intent from a screen component. For example:
{
"operationId": "client-generated-id",
"entityType": "task",
"entityId": "task-123",
"operation": "update",
"payload": { "completed": true },
"baseVersion": 18,
"status": "pending",
"attempts": 0,
"nextAttemptAt": "timestamp",
"createdAt": "timestamp",
"lastError": null
}The exact serialization format can vary. The important properties are durability, inspectability, stable identity, and a payload that the server can process safely more than once.
When connectivity returns
- Trigger a sync attempt from the connectivity listener, app foreground event, and selected user actions.
- Coalesce duplicate triggers so several events do not start concurrent sync workers.
- Process operations in a predictable order, especially when several changes affect one entity.
- Use bounded retries with increasing delays and a limit on work per run.
- Refresh server data after mutations so local state reflects server-side validation and derived fields.
- Persist queue status after every meaningful transition, not only at the end of a batch.
Background execution is platform-controlled. Do not design a workflow that depends on unlimited background JavaScript or continuous connectivity. A foreground retry path, a visible pending state, and a safe resume after app launch are essential even when background synchronization is available.
When a request times out or is interrupted
Treat an ambiguous result as unknown, not automatically failed. The server may have committed the write even though the response did not reach the device. Retry using the same operation ID, and make the server endpoint idempotent so it can return the original result or an equivalent acknowledgement when it receives that ID again.
- Keep the operation in the queue.
- Mark its outcome as unknown or retryable rather than deleting it.
- Retry with the original operation ID after the backoff period.
- Reconcile the returned entity and version with local state.
- Only remove the queue item after a durable success or a deliberate resolution.
When a conflict is returned
Define conflict behavior per entity instead of applying one universal rule. A task completion flag may use a simple server-wins or latest-valid-change rule, while a financial record, booking, or collaborative note may require user review.
| Conflict type | Possible policy | UI response |
|---|---|---|
| Non-critical preference | Latest accepted value | Apply quietly and show a brief status if needed |
| Independent fields | Field-level merge | Show the merged result and changed fields |
| Append-only event | Keep both events using unique IDs | Show the resulting history |
| Destructive or consequential edit | Require explicit review | Present local and server versions with choices |
Never silently overwrite user work when the cost of being wrong is high. Store enough metadata to explain which version won and why.
What to double-check
Connectivity and device APIs
- Verify that your network-status integration handles transitions, unknown states, and repeated events without causing a sync loop.
- Test Wi-Fi to cellular changes, airplane mode, captive networks, and a reachable network with an unavailable API.
- Keep permission and native configuration requirements separate from application-level sync logic.
- Confirm that the chosen Expo or native module version matches the project’s React Native setup.
For related device-facing concerns, review the React Native Permissions Guide and the React Native Error Handling and Crash Reporting guide. Offline behavior should be observable: record queue length, sync duration, failure category, and the last successful sync without logging sensitive payloads.
Authentication and authorization
A queued operation may outlive an access token. When a request is unauthorized, pause the queue, renew the session through the app’s normal authentication flow, and resume only after the user is authenticated. Do not place long-lived secrets or unnecessary personal data in a queue. See the React Native Authentication Patterns guide for session and logout considerations.
Schema and migrations
- Version local schemas and define migrations before changing serialized records.
- Retain compatibility for queued operations created by older app versions when practical.
- Define behavior for deleted server records, renamed fields, and invalid enum values.
- Decide whether logout clears all local data, account-specific data, or only sensitive data.
Connectivity-state UI checklist
- Online: normal experience, with no unnecessary banner.
- Offline: show available cached data and explain which actions are queued.
- Syncing: show progress or a subtle status without blocking unrelated screens.
- Pending: identify records that have not reached the server.
- Conflict: provide a review action and preserve both versions where needed.
- Failed: explain the next action, such as retry, sign in again, or contact support.
Include accessibility labels for status icons, localize dates and messages, and avoid relying on color alone. The localization workflow in the React Native Internationalization and Localization guide is relevant when sync messages need to work across languages and layouts.
Common mistakes
- Deleting a request after a timeout: the server may have accepted it. Retry idempotently and reconcile the result.
- Using the cache as the queue: cached entities do not describe intent, ordering, or retry state. Keep mutation records separately.
- Starting multiple sync workers: foreground events, connectivity events, and manual refresh can overlap. Use a single serialized worker or a lock.
- Assuming “online” means usable: confirm the API response and classify failures by authentication, validation, server, and transport causes.
- Overwriting conflicts silently: choose a policy per entity and expose review for consequential changes.
- Storing only the final local value: without a base version and operation identity, conflict diagnosis becomes guesswork.
- Testing only a clean airplane-mode demo: also interrupt requests, kill the app during writes, change accounts, fill storage, and upgrade the local schema.
Build these cases into automated tests and device tests. The React Native Testing Strategy guide can help separate unit tests for queue rules from integration and end-to-end tests for interrupted network flows.
When to revisit
Revisit this checklist before seasonal planning cycles, before a major schema or authentication change, and whenever your storage, networking, Expo, React Native, or native platform configuration changes. Also review it after incidents involving duplicate writes, missing data, stuck queues, or users seeing different records on different devices.
Use this practical recovery workflow during an incident:
- Capture the local entity, operation ID, queue status, base version, and last error without exposing sensitive content.
- Determine whether the request was never sent, failed before a response, was rejected, or may have succeeded ambiguously.
- Query the server by operation ID or entity version where the API supports reconciliation.
- Compare local and server records and apply the documented conflict policy.
- Repair the local record and queue transactionally, then run a fresh synchronization.
- Record the scenario as a regression test before closing the incident.
Finally, verify the implementation on both platforms and on the supported project configuration. Recheck background limitations, native connectivity APIs, storage serialization, and package compatibility whenever workflows or tools change. An offline-first design is reliable when every operation can be explained, resumed, and safely reconciled—not merely when a cached screen appears during airplane mode.