All articles Engineering · React Native

React Native offline sync: a practical guide

Most Nigerian users don't have reliable connectivity. They move between 4G, 3G, Wi-Fi, and no signal in a single commute. If your app requires the network to function, it will feel broken half the time — regardless of how good your backend is.

This is the single most important lesson from building TaskForge, a cross-platform task manager that hit 4,200+ users in 90 days. Here's how we approached offline-first sync, and the mistakes I'd avoid next time.

What "offline-first" actually means

Offline-first is a design philosophy, not a technical trick. The core idea: your app should be fully usable with zero network. The network is treated as an optimization, not a requirement.

In practice, this means every user action — creating a task, updating a status, adding a comment — writes to a local store first. A background process syncs that store with the server when the network is available.

The three layers of an offline-first app

1. Local persistence

We used AsyncStorage for small data and react-native-sqlite-storage for structured task data. SQLite gives you query power and transactional writes, which matters once your data grows past a few hundred records.

// Example: writing a task locally first
await db.executeSql(
  `INSERT INTO tasks (id, title, status, updated_at, synced)
   VALUES (?, ?, ?, ?, 0)`,
  [uuid(), title, 'todo', Date.now()]
);

Notice the synced column. Every row has a flag that tells the sync engine whether it needs to be pushed to the server. Simple, reliable, and easy to reason about.

2. A sync queue

When a user creates or updates a task, we don't call Firebase immediately. We queue the operation locally. The queue is persisted, so it survives app restarts.

type SyncOp = {
  id: string;
  entity: 'task' | 'comment';
  action: 'create' | 'update' | 'delete';
  payload: unknown;
  createdAt: number;
};

A background worker processes the queue when the device is online. On success, it removes the op. On failure, it retries with exponential backoff.

3. Conflict resolution

When two devices edit the same task offline, someone has to win. We chose last-write-wins based on a server timestamp. It's not perfect, but it's predictable — and predictability beats cleverness for most teams.

The three mistakes I'd avoid next time

Mistake 1: Adding analytics in week six

We had no visibility into how users actually used the app until week six. That's six weeks of building on assumptions. Add analytics — even just basic event tracking — from day one.

Mistake 2: Underestimating the offline data model

We initially designed the sync layer assuming a single device per user. Reality: 40% of users had two devices (phone + tablet). That required reworking the conflict resolution. Design for multi-device from the start.

Mistake 3: Not testing on real Nigerian networks

Simulators lie. A 2G connection on an emulator is not the same as a real MTN connection in Benin City at 7 PM. We started testing on real devices with real SIMs in week four — and immediately found three bugs we'd never have caught otherwise.

Tools that made this easier

Is offline-first worth it?

For most Nigerian-facing products, yes. The UX difference is dramatic. Users stop noticing connectivity. The app feels fast even on 2G. And retention improves — TaskForge hit 18% D30 retention, which is roughly double the industry average for productivity apps.

The trade-off is complexity. Sync logic is hard to get right. But if your users are in an environment where networks are unreliable, it's the single highest-leverage investment you can make.

Building something similar?

I'm currently accepting new work for Q1 2026.