Offline sync in React Native: local data, queues and conflict rules.

1. Offline mode is a product decision, not only storage

Offline support starts before choosing AsyncStorage, SQLite or another local database. The first decision is what the app must allow when the network disappears and what must wait for the backend.

A field app, inspection app or management app may need to create drafts, attach photos, update status or complete checklists without reliable connectivity. Each action has a different business risk.

• List which flows can work without network.
• Separate drafts, local-only actions and server-confirmed actions.
• Define what the user can see, edit and submit while offline.
• Avoid pretending that every successful tap is already a backend success.

2. Define local data boundaries

Not every API response should live on the device. Some data is useful for experience, some data is sensitive, and some data becomes risky when it is stale.

A good offline contract says which entities can be cached, for how long, under which user profile and how the app invalidates them when the session changes.

• Identify data that is safe to cache.
• Avoid storing secrets or unnecessary personal data.
• Tie local data to the authenticated user and tenant when relevant.
• Define expiration rules for stale content.
• Clean local state after logout or profile switch.

3. Use a sync queue for pending operations

When an action cannot reach the backend, the app needs a place to store intent. A sync queue turns pending work into explicit state: what should be sent, when it was created, how many attempts happened and what the latest error was.

The queue should be understandable to the product and support teams. If a user says a task is stuck, the app needs evidence beyond "something failed".

• Store operation type, payload, local identifier and timestamp.
• Track attempt count and last error category.
• Keep a visible pending state for the user when the action matters.
• Make retry behavior predictable instead of hidden in random effects.
• Avoid sending the same operation twice without idempotency rules.

{
  "localId": "pending_927",
  "operation": "task.complete",
  "createdAt": "2026-06-30T19:20:00-03:00",
  "attempts": 1,
  "status": "pending",
  "payload": { "taskId": "t_42", "completed": true }
}

4. The API contract must support synchronization

A mobile app cannot solve offline alone. The backend needs predictable identifiers, timestamps, validation errors and idempotency behavior so the app can retry safely.

If two requests represent the same local operation, the server should know how to accept a retry without duplicating business effects.

• Use client-generated request IDs for idempotent operations.
• Return stable error formats that the app can map to retry, user action or discard.
• Expose update timestamps or version fields where conflict detection matters.
• Keep status codes consistent between online and retry scenarios.
• Log correlation IDs for synchronized operations.

5. Conflict rules must be explicit

Conflicts happen when the local action and the server state disagree. The worst approach is to let the app silently choose a winner without the business knowing.

Some domains can use last-write-wins. Others need manual review, server priority, role priority or field-level merge. The rule should be part of the product behavior, not an accident in the code.

• Decide whether the server, device or reviewer wins each conflict.
• Show a useful explanation when an action cannot be synchronized.
• Keep enough local evidence for support to understand the case.
• Avoid overwriting server data without a deliberate rule.
• Treat attachments, status changes and financial records with extra care.

6. Users need clear offline feedback

Offline behavior fails when the app hides uncertainty. Users should know when data is saved locally, when it is pending synchronization, when it is confirmed by the server and when action is required.

The UI does not need to be noisy. It needs to be honest. A small pending badge, sync screen or retry message is better than pretending everything was completed.

• Differentiate local draft from server-confirmed success.
• Show pending operations in a place the user can understand.
• Offer retry when the user can help, and automatic retry when they cannot.
• Avoid blocking the whole app because one operation is pending.
• Make destructive actions harder while offline.

7. Release checklist for offline sync

Offline sync should be tested with real interruptions, slow networks, app restarts, expired sessions and backend validation errors.

The release is safer when the team treats offline as a workflow with evidence, not as a checkbox in the feature list.

• Test airplane mode before, during and after an operation.
• Restart the app with pending items in the queue.
• Expire the token while sync is pending.
• Return validation errors from the backend and confirm the UI response.
• Test duplicate retry with the same idempotency key.
• Confirm that logout clears or protects local data.
• Collect analytics and logs for pending, synced, failed and discarded operations.