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
- Firebase Firestore: built-in offline persistence for reads and writes
- NetInfo: for detecting connection state changes
- Redux Persist: keeping app state across restarts
- Flipper: debugging network and storage in real time
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.