Implementing Offline Functionality in React Native Apps

Mobile users spend a significant portion of their time in areas with poor or no connectivity—subways, elevators, airplanes, rural regions, and buildings with weak signals. An app that shows a blank screen or a generic error when the network drops provides a fundamentally broken user experience. Offline-first architecture designs the app to work locally by default, treating network connectivity as an enhancement rather than a requirement. Data is stored locally, user actions are queued, and synchronization happens seamlessly when connectivity is restored. This approach dramatically improves perceived performance (local reads are instant) and reliability.

AsyncStorage (from `@react-native-async-storage/async-storage`) provides a simple, unencrypted, asynchronous key-value store. It is ideal for persisting user preferences, authentication tokens, small JSON objects, and cached API responses. Use `await AsyncStorage.setItem('user_settings', JSON.stringify(settings))` to save and `JSON.parse(await AsyncStorage.getItem('user_settings'))` to retrieve. AsyncStorage has practical size limits (6MB on Android by default) and is not suitable for large datasets, complex queries, or structured relational data. For those needs, use a proper database.

For apps that need to query structured data offline—filtering, sorting, joining tables, full-text search—SQLite via `react-native-sqlite-storage` or `expo-sqlite` is the right choice. SQLite provides a full SQL engine running locally on the device. Create tables, insert records, and execute complex queries with joins, aggregations, and indexes. A field service app, for example, can store thousands of work orders with customer details, parts lists, and completion statuses, allowing technicians to search and update records entirely offline. SQLite databases can grow to gigabytes without performance issues, making them suitable for data-intensive applications.

Realm (now part of MongoDB Atlas Device SDK) is an object-oriented mobile database designed for React Native. Unlike SQLite's SQL interface, Realm uses a native object API: define a schema class, then query with `realm.objects('Task').filtered('status == "pending"').sorted('dueDate')`. Realm's killer feature is live objects—any query result automatically updates in real-time when underlying data changes, eliminating manual state management. Combined with Atlas Device Sync, Realm provides automatic bidirectional sync between the device and MongoDB Atlas, handling conflict resolution, network partitions, and retry logic out of the box.

Accurate network detection is the foundation of offline-aware UX. Use `@react-native-community/netinfo` to subscribe to connectivity changes: `const unsubscribe = NetInfo.addEventListener(state => { setIsConnected(state.isConnected); setConnectionType(state.type); })`. The library provides not just a boolean connected/disconnected state, but the connection type (wifi, cellular, ethernet) and whether the connection is actually reachable (a device can be connected to WiFi that has no internet access). Use this information to display contextual UI: a subtle offline banner, a "changes will sync when online" message, or a full offline mode indicator.

The most complex challenge in offline-first apps is synchronizing data when connectivity resumes. Queue user actions locally using an operations log pattern: each create/update/delete action is stored as a timestamped operation in a local queue. When online, replay the queue sequentially against the server. For conflict resolution, implement one of three strategies: Last-Write-Wins (simplest—timestamp-based), Server-Wins (server state always takes precedence), or Merge (field-level conflict resolution using operational transforms). Use the stale-while-revalidate pattern for reads: serve cached data immediately while fetching fresh data in the background, then update the UI when the response arrives.

Optimistic UI updates apply user actions to the local state immediately, before server confirmation. When a user marks a task as complete, the checkbox animates instantly and the task moves to the "completed" section—the server request happens asynchronously in the background. If the server request fails, the UI rolls back the change and shows an error notification. This pattern makes the app feel instantaneous regardless of network conditions. Implement with a state management library like Zustand or Redux, maintaining both a "committed" state (server-confirmed) and an "optimistic" state (locally applied), and reconciling them when the server responds.

Data stored on device must be protected. Encrypt sensitive data using `react-native-keychain` for credentials and tokens, and `realm.open({ encryptionKey })` for encrypted Realm databases. Never store raw API keys, passwords, or PII in AsyncStorage without encryption. For testing offline scenarios, use Airplane Mode toggling on physical devices, the Network Link Conditioner on iOS Simulator, and Android Emulator's network throttling to simulate various connectivity conditions. Write integration tests that verify: the app renders cached data when offline, user actions are queued correctly, and synchronization completes successfully when connectivity is restored.