The Challenge of True Offline-First Architecture
Building offline-first web applications requires moving far beyond simple HTTP GET response caching. While caching read requests allows users to view previously fetched data without a network connection, true offline-first functionality demands full write capability: capturing local mutations, persisting them across sessions, maintaining deterministic execution order, and reconciling conflicts gracefully once connectivity is restored.
TanStack Query (v5) offers powerful client-side cache orchestration, but out-of-the-box it keeps state in volatile memory. By coupling TanStack Query with an IndexedDB persistor layer and a deterministic mutation queue, software engineers can architect resilient web applications that provide immediate feedback and guaranteed eventual consistency—even through page reloads, browser crashes, and intermittent connectivity.
Architecture Blueprint: The Offline State Pipeline
An enterprise-grade offline-first system rests on three foundational layers: volatile runtime cache management, durable persistence via browser storage, and an asynchronous network synchronization engine.
- Runtime Memory Layer (TanStack Query Cache): Provides instant reads and optimistic UI updates.
- Persistence Engine (IndexedDB): Stores serialized Query and Mutation caches asynchronously, overcoming the 5MB limits and synchronous blocking nature of
localStorage. - Synchronization & Dispatcher Layer: Monitors connectivity via
onlineManager, pauses unexecuted mutations, and flushes queued operations in sequence upon reconnection.
Building a Robust IndexedDB Persistor
Using localStorage for state persistence poses severe risks: synchronous execution blocks the main thread, and strict storage quotas (usually 5MB) trigger unhandled exceptions when cache sizes grow. IndexedDB provides asynchronous execution and gigabytes of structured storage capacity.
Using idb-keyval—a lightweight wrapper around IndexedDB—we can build a high-performance custom persistor that implements TanStack Query's Persister interface with built-in write throttling to avoid excessive I/O churn during rapid updates.
Deterministic Mutation Queues and Optimistic UI
The core challenge of offline writes is preserving the exact sequence of user actions. If a user edits an item and subsequently deletes it while offline, processing the deletion before the edit will crash the server endpoint. TanStack Query v5 handles this through mutation pausing and persistent mutation metadata.
When network connectivity drops, mutations configured with networkMode: 'offlineFirst' are paused and appended to the mutation cache. When paired with a persistor, these paused mutations survive tab closures and device reboots.
Conflict Resolution Strategies: Server-Authoritative Merge
When the client reconnects, the persisted queue flushes. If server state changed while the client was offline, optimistic assumptions may fail. To resolve conflicts cleanly, applications should adopt a Last-Write-Wins (LWW) with Version Vector approach or a Server-Authoritative Merge strategy.
By sending a client-side timestamp or version token alongside the mutation payload, the backend can evaluate whether the update is stale and return updated entity state, which TanStack Query's onSettled callback integrates into the local cache.
Cross-Tab Synchronization and Hydration Race Conditions
When running an offline-first application across multiple browser tabs, race conditions occur if Tab A updates IndexedDB while Tab B holds an outdated memory state. Utilizing the Web BroadcastChannel API prevents cache divergence across concurrent instances.
Conclusion
Architecting offline-first web applications using TanStack Query Persistors and IndexedDB turns unpredictable network environments from fatal failure points into seamless background transitions. By leveraging asynchronous non-blocking storage, deterministic mutation queues, optimistic cache updates, and cross-tab communication channels, engineering teams can deliver native-app speed and resilience within the open web standard.