Offline-first React apps are built so they keep working when the network drops, syncing data once connectivity returns. This article explains the core strategies—service workers, local storage, and sync logic—and shows you how to implement them for unreliable networks.
Why Offline-First Matters
Users in areas with poor connectivity, on flaky mobile data, or in transit expect apps to not freeze or lose their work. An offline-first approach treats the network as an enhancement, not a requirement. It improves perceived performance because the UI responds instantly from local data, and it reduces server load by batching syncs. For React developers, this means designing state management and data fetching around a local source of truth, with background synchronization as a separate concern.
Core Building Blocks
Three technologies form the foundation of most offline-first React apps:
- Service Workers – A script that runs in the background, intercepting network requests. It can serve cached assets (via Cache API) and even cache API responses for offline reading.
- Local Storage Options – IndexedDB (via libraries like idb or Dexie) for structured data, or localStorage for simple key-value pairs. IndexedDB is asynchronous and can store blobs, making it better for large datasets.
- Synchronization Engine – Code that queues actions while offline and replays them when online. Libraries like Redux Offline, React Query, or SWR can handle this, or you can write custom logic.
How to Build: Step-by-Step
- Set up a service worker – Use Workbox to precache your app shell (HTML, JS, CSS) so the app loads from cache on repeat visits. For dynamic content, implement a runtime caching strategy (stale-while-revalidate works well for API responses).
- Choose a local database – For most apps, IndexedDB is the right choice. Use a wrapper like Dexie to simplify the API. Store the latest server data here as your cache.
- Make your React state reflect local data – Instead of fetching from the network on every action, read from IndexedDB first. Libraries like React Query can be configured with a
placeholderDatafrom local cache. - Queue user actions – When the user creates or edits data, write it to IndexedDB immediately and add a pending operation to a queue (e.g., an array in IndexedDB).
- Sync when online – Listen to the
onlineevent (andnavigator.onLinechecks). When back online, process the queue: send mutations to the server, handle conflicts, then update the local cache with the server response.
Handling Synchronization Conflicts
When two devices edit the same record offline, you need a conflict resolution strategy. Common approaches:
- Last-write-wins – Simple, but can lose data. Use a timestamp or version number.
- Field-level merge – Merge changes at the field level if they don’t overlap.
- Operational transforms – More complex; used by collaborative editors.
- Manual resolution – Present the user with both versions and let them choose.
For most apps, last-write-wins with a version field is acceptable. If you need stronger guarantees, consider using a backend with built-in sync (like Firebase or Supabase) that handles conflict resolution for you.
Common Pitfalls and Misconceptions
A frequent mistake is assuming that a service worker alone makes an app offline-first. Caching assets is not enough—you need to handle data mutations and sync. Another pitfall is not handling the case where the user closes the tab while offline; the queue must be persisted in IndexedDB, not in memory. Also, be aware of the browser’s storage limits (especially for Safari) and clean up old data to avoid quota exceeded errors.
A common misconception is that offline-first is only for mobile apps. It’s equally valuable for web apps used in areas with intermittent connectivity, on trains, or in buildings with poor Wi-Fi. It also improves performance for all users by reducing latency.
Tools and Libraries Comparison
Here’s how popular React data-fetching libraries handle offline:
- React Query – Provides caching and background refetching, but does not queue mutations out of the box. You’d need to add your own mutation queue.
- SWR – Similar to React Query; focuses on caching and revalidation, not offline mutations.
- Redux Offline – A dedicated library for offline-first Redux apps, handling action queuing and replay. It’s less maintained now but still works.
- Firebase/Supabase – Backend-as-a-service with built-in offline support and conflict resolution. They provide SDKs that handle local storage and sync automatically.
If you’re starting a new project, consider using a BaaS to save time. If you need full control, build your own with IndexedDB and a queue.
Performance and Storage Considerations
Offline-first apps can consume significant storage. IndexedDB is not limited to 5MB like localStorage, but browsers still impose quotas (often around 60% of available disk). To avoid issues:
- Only cache data the user is likely to need offline—not the entire database.
- Implement a cache eviction policy (e.g., least recently used).
- Compress large payloads before storing.
- Inform the user when storage is low (via the Storage API).
Performance-wise, reading from IndexedDB is fast, but be careful not to block the main thread. Use async/await and consider Web Workers for heavy processing.
Testing and Debugging
Testing offline behavior requires simulating network failures. In Chrome DevTools, you can set the network to ‘Offline’ and test. For automated tests, use Playwright or Cypress to toggle the network. Also, test on real devices with airplane mode.
Common debugging tools:
- Service worker panel in DevTools to inspect caches and update cycles.
- IndexedDB explorer to view stored data.
- Network throttling to simulate slow connections.
Frequently Asked Questions
Can I use localStorage instead of IndexedDB for offline data?
Yes, for small amounts of data (under 5MB) and simple key-value pairs. However, localStorage is synchronous and blocks the main thread, and it can only store strings. For most offline-first apps, IndexedDB is more suitable.
How do I know when the app is back online?
Listen to the online and offline events on the window object. Also check navigator.onLine initially. Note that these events are not always reliable on mobile browsers, so also watch for successful network requests.
What is the difference between offline-first and offline-only?
Offline-first means the app works offline but also uses the network when available for syncing and fetching fresh data. Offline-only means the app never requires a network connection; it’s typically used for local-only apps like note-taking with no cloud sync.
Do service workers work on all browsers?
Service workers are supported in all modern browsers (Chrome, Firefox, Safari, Edge). Safari had some limitations in the past, but as of Safari 11.1, it supports service workers. For older browsers, you may need a fallback to a simple cache or an online-only experience.
How do I handle authentication when offline?
You should store the user’s session token securely (e.g., in IndexedDB or a cookie) and allow them to use the app offline. When back online, validate the token with the server. Be aware that tokens may expire; you can refresh them in the background.