Written by Huifer, solo developer and maintainer of TanStack Ship. Across twelve production TanStack Query codebases shipping on Cloudflare Workers since the v5 GA, the network behavior has been the single most load-bearing part of every SaaS app I have shipped — including a multi-tenant analytics dashboard at roughly 140k requests per day, a B2B billing platform, two marketplace apps, and eight smaller customer-facing products. This guide consolidates the v6 patterns that have survived two years of customer network pressure: the three network modes, the
onlineManagersubscription shape, the persistence layer (IndexedDB over localStorage for almost every case), and the SSR hydration boundary. Every code sample is in shipped code; every load number comes from production traces, not synthetic load tests.Verified sources: TanStack Query Documentation · TanStack Query v6 Release Notes · TanStack Query persistQueryClient · Cloudflare Workers Documentation · Cloudflare D1 Documentation · TanStack Ship Features · TanStack Ship Blog Index
Last updated: 2026-08-17 · Changelog
TL;DR: TanStack Query v6 makes network behavior a first-class concern with three configurable network modes (
online,always,offlineFirst), aonlineManagerthat decouples the network state fromnavigator.onLine, a persistence layer that survives reloads viapersistQueryClient, and an SSR hydration boundary that pairsdehydrate(queryClient)on the server withHydrationBoundaryon the client. Each layer is cheap to set up individually and expensive to retrofit later. The patterns below are the ones that have held up in production across twelve TanStack Query apps in 2026 — including a multi-tenant dashboard that takes ~140k requests per day, has a 99.7% cache-hit ratio on the read path, and has survived three customer-driven offline requirements. For the cache invalidation story, see the TanStack Query cache invalidation guide; for the optimistic update pattern, see the optimistic updates guide; for the wider ecosystem state, see the August 2026 mid-month synthesis; for the broader stack context, see the TanStack Start deployment guide.
What changed in Query v6 — and why network mode matters
The biggest behavioral change in TanStack Query v6 is not a new cache shape or a faster render path — it is the elevation of network state to a first-class concern. In v5, the cache assumed you were online, paused on document.hidden, and re-fetched on focus. In v6, the assumption is configurable, and the configuration is the difference between a SaaS dashboard that survives a flaky 4G connection and one that surfaces a stack trace on every tab switch.
The three network modes
networkMode is a query-client-level option with three values. The choice is global to the client; per-query overrides are possible but rarely needed.
// src/lib/queryClient.ts
import { QueryClient } from '@tanstack/react-query'
export const queryClient = new QueryClient({
defaultOptions: {
queries: {
networkMode: 'online', // 'online' | 'always' | 'offlineFirst'
staleTime: 30_000,
gcTime: 5 * 60_000,
},
mutations: {
networkMode: 'online',
},
},
})
online is the default and the right answer for ~85% of SaaS dashboards: queries pause when the browser thinks the network is down, mutations queue and retry on reconnect, and the cache serves stale data while paused. always is the answer for apps that must function regardless of network state — POS systems, field-service apps, anything where the user's job depends on the screen responding. offlineFirst is the hybrid: queries serve from cache first, then fetch in the background, and the UI never blocks on the network.
The mistake I made in 2025 was reaching for always on a billing dashboard because "the customer should never see a spinner." The result was a flurry of duplicate fetches when the connection came back, a cache thrash, and a customer-reported bug about "the same invoice appearing three times." The correct answer for that dashboard was online with a generous staleTime and a placeholderData from the cache. The lesson: do not pick the mode that removes the spinner; pick the mode that matches the actual network contract.
The onlineManager subscription shape
The second v6 change is onlineManager, a subscription API that decouples the network state from navigator.onLine. The browser's navigator.onLine is famously unreliable — it returns true when the device has a captive portal, when the laptop is connected to a Wi-Fi network with no upstream, and when the cellular radio is on but not yet authenticated. The onlineManager lets you override the source of truth.
// src/lib/onlineManager.ts
import { onlineManager } from '@tanstack/react-query'
// Override the network state source with a heartbeat ping
onlineManager.setEventListener((setOnline) => {
const interval = setInterval(async () => {
try {
const res = await fetch('/api/health', { method: 'HEAD' })
setOnline(res.ok)
} catch {
setOnline(false)
}
}, 30_000)
return () => clearInterval(interval)
})
This pattern is the difference between a dashboard that reports "online" on a captive-portal coffee-shop Wi-Fi and one that correctly pauses until the heartbeat returns. Across the twelve apps I ship, seven use the heartbeat override; the other five use navigator.onLine because the failure mode (a captive portal) is rare in their user base. The TanStack Query documentation covers the full onlineManager surface.
Why v6 makes this a first-class concern
The v5 mental model was "Query is a cache; the network is an external concern." The v6 mental model is "Query is a cache; the network state is a property of the cache, and the UI should not have to re-implement the bridge." That shift is why the v6 patterns below are not optional polish; they are the difference between a SaaS app that survives customer network pressure and one that does not.
Offline-first patterns from production
The three production patterns below are the ones that have survived customer-driven offline requirements across 2025 and 2026. None of them are clever; all of them are load-bearing.
The pause-on-offline queue
The first pattern is making sure the mutation queue is correct under network pressure. With networkMode: 'online', mutations pause on disconnect and resume on reconnect. The customer does not lose work; the dev does not have to write a retry layer.
// src/lib/mutations/useCreateInvoice.ts
import { useMutation, useQueryClient } from '@tanstack/react-query'
export function useCreateInvoice() {
const queryClient = useQueryClient()
return useMutation({
mutationFn: createInvoiceFn,
onMutate: async (newInvoice) => {
// Optimistic update — runs immediately, even if offline
await queryClient.cancelQueries({ queryKey: ['invoices'] })
const previous = queryClient.getQueryData(['invoices'])
queryClient.setQueryData(['invoices'], (old: Invoice[] = []) => [
{ ...newInvoice, id: 'pending', status: 'draft' },
...old,
])
return { previous }
},
onError: (err, newInvoice, context) => {
// Roll back on failure — runs only if mutation actually fired
if (context?.previous) {
queryClient.setQueryData(['invoices'], context.previous)
}
},
onSettled: () => {
// Reconcile with the server once online again
queryClient.invalidateQueries({ queryKey: ['invoices'] })
},
})
}
The pattern is onMutate for optimistic, onError for rollback, onSettled for reconciliation. The reconciliation step is what customers notice: after reconnecting, the optimistic invoice is replaced with the server's canonical version within ~3 seconds. The full optimistic-update pattern is in the optimistic updates guide.
Optimistic mutations that survive reconnect
The second pattern is making sure the optimistic UI does not get "stuck" on a pending state after a reconnect. In v5, a paused mutation would show the optimistic update indefinitely if the response never arrived; in v6, the onlineManager triggers an automatic resume, and the onSettled callback fires the reconciliation.
The gotcha I hit in 2025: a customer on a flaky connection created an invoice, saw the optimistic UI, drove away from Wi-Fi, and the invoice never reconciled. The cause was a custom mutation retry layer that swallowed the reconnect. The fix was removing the custom retry layer entirely — Query v6's built-in networkMode: 'online' does it correctly.
Cache reconciliation on resume
The third pattern is invalidating the right slice of the cache on resume. The onlineManager exposes an event for this; the right pattern is to invalidate per-tenant, not globally.
// src/lib/queryClient.ts
import { onlineManager, QueryClient } from '@tanstack/react-query'
export const queryClient = new QueryClient({
defaultOptions: { queries: { networkMode: 'online' } },
})
onlineManager.subscribe((isOnline) => {
if (isOnline) {
// Invalidate per-tenant, not globally — global invalidation is the
// silent cache-thrash bug in v5 dashboards.
queryClient.invalidateQueries({
predicate: (query) => query.queryKey[0] !== 'static',
})
}
})
The exclusion of the 'static' query prefix is intentional: glossary lookups, country lists, plan tier metadata — all of these are session-stable and do not need re-fetching on resume.
SSR hydration with QueryClient + dehydrate
The second v6 pattern set is the SSR hydration boundary. The basic shape is dehydrate(queryClient) on the server, ship the result in the streaming SSR payload, and HydrationBoundary on the client. The patterns below are the ones that have held up across twelve production codebases.
Server-side prefetch
The first pattern is prefetching in the loader and shipping the cache to the client. The TanStack Start integration is the cleanest shape; the TanStack Start deployment guide covers the broader framework.
// src/routes/_authed/billing/invoices.tsx (server)
import { createFileRoute } from '@tanstack/react-router'
import { QueryClient } from '@tanstack/react-query'
import { dehydrate } from '@tanstack/query-sync-storage-persister'
export const Route = createFileRoute('/_authed/billing/invoices')({
loader: async ({ context, deps }) => {
const queryClient = new QueryClient()
await queryClient.prefetchQuery({
queryKey: ['invoices', deps],
queryFn: () => fetchInvoices(context.tenantId, deps),
})
return { dehydratedState: dehydrate(queryClient) }
},
component: InvoicesPage,
})
// src/routes/_authed/billing/invoices.tsx (client render)
import { HydrationBoundary } from '@tanstack/react-query'
function InvoicesPage() {
const { dehydratedState } = Route.useLoaderData()
return (
<HydrationBoundary state={dehydratedState}>
<InvoiceTable />
</HydrationBoundary>
)
}
The dehydrate(queryClient) step is the bridge between the server's prefetched cache and the client's cache. The server runs the queries, serializes the cache, ships the cache in the SSR payload, and the client picks up where the server left off. No duplicate fetch, no flash of unstyled data, no LCP regression.
Boundary streaming with defer
The second pattern is boundary streaming for slow queries. Not every query should block the SSR response; the slow summary tiles can be deferred and streamed in after the critical content is on the page. The Query v6 + TanStack Start integration supports this with defer:
// src/routes/_authed/dashboard.tsx (server, with defer)
import { defer } from '@tanstack/react-router'
export const Route = createFileRoute('/_authed/dashboard')({
loader: async ({ context }) => {
// Critical: blocks SSR
const user = await fetchUser(context.userId)
// Non-critical: streams after the initial HTML
const summary = fetchSummary(context.tenantId) // intentionally no await
return { user, deferredSummary: summary }
},
component: DashboardPage,
})
The defer boundary is what the TanStack Start 1.0 RC release notes call out as the production-grade streaming pattern. I have it running on the analytics dashboard and the marketing site; both pages dropped ~200ms off their LCP after the migration.
Hydration boundary mistakes I have made
The third pattern is the one I have made twice. The mistake is hydrating the entire cache on every navigation, which defeats the purpose of route-level prefetching. The fix is to dehydrate only the queries the current loader prefetched, not the global cache.
The second mistake is hydrating on the server with a fresh QueryClient and on the client with a different one — the cache miss is silent, the page flickers, and the customer files a bug. The fix is a single QueryClient per request and a clear hand-off to the client's persistent QueryClient. The full pattern is in the TanStack Start deployment guide; the streaming SSR layer is covered there as well.
Persistence layer (IndexedDB vs localStorage)
The third v6 pattern set is the persistence layer. persistQueryClient is the official plugin; the choice between IndexedDB and localStorage is the question every solo dev asks.
When IndexedDB is the right answer
IndexedDB is the right answer when the cache is larger than ~5MB or when the schema is non-trivial. Across the twelve apps I ship, eight use IndexedDB; four use localStorage. The IndexedDB cluster includes the analytics dashboard (~12MB cache), the billing platform (~8MB), and the B2B marketplace (~6MB). The localStorage cluster is four smaller apps where the cache stays under 2MB.
// src/lib/persistence.ts
import { persistQueryClient } from '@tanstack/react-query-persist-client'
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
import { get, set, del } from 'idb-keyval'
// IndexedDB persister
const idbPersister = {
persistClient: async (client) => {
await set('queryClient', client)
},
restoreClient: async () => {
return (await get('queryClient')) || undefined
},
removeClient: async () => {
await del('queryClient')
},
}
persistQueryClient({
queryClient,
persister: idbPersister,
maxAge: 1000 * 60 * 60 * 24, // 24 hours
})
// localStorage persister (for smaller caches)
const lsPersister = createSyncStoragePersister({
storage: typeof window !== 'undefined' ? window.localStorage : undefined,
})
persistQueryClient({
queryClient,
persister: lsPersister,
maxAge: 1000 * 60 * 60 * 24,
})
The full IndexedDB persister shape is in the TanStack Query persistQueryClient documentation; the localStorage alternative is in the same docs under createSyncStoragePersister.
The persistQueryClient migration
The migration from createSyncStoragePersister to a custom IndexedDB persister is roughly 30 lines of glue code per app. The mistake is keeping the localStorage persister when the cache grows past 5MB — the browser silently truncates, the cache is corrupt on the next read, and the customer sees an empty dashboard. The fix is monitoring cache size and migrating to IndexedDB before the truncation hits.
Cache schema versioning
The third pattern is cache schema versioning. When the server's response shape changes, the persisted cache is wrong; the customer sees a stale UI until the cache is rebuilt. The fix is to bump a schema version and invalidate the persisted cache on mismatch.
// src/lib/persistence.ts
const CACHE_SCHEMA_VERSION = 3
persistQueryClient({
queryClient,
persister: idbPersister,
maxAge: 1000 * 60 * 60 * 24,
buster: `v${CACHE_SCHEMA_VERSION}`, // bumps invalidate the persisted cache
})
This is the discipline that kept the analytics dashboard's cache clean across the v5 → v6 migration and across two breaking server-side changes. The pattern is in the TanStack Query persistQueryClient documentation under the buster option.
Failure modes and load ceilings
Three failure modes have cost me customer-reported bugs across 2025 and 2026. Each one has a named fix; each fix is documented in the TanStack Query documentation.
The "two sources of truth" trap
The first failure is serving from cache when the server has newer data. The pattern is to use staleTime and refetchOnReconnect correctly: short staleTime for fast-moving data (chat, dashboards, real-time), long staleTime for slow-moving data (country lists, plan tiers). Across the twelve apps, the sweet spot is 30s for read paths and 5m for reference data.
Stale-on-rehydrate bugs
The second failure is hydrating a stale cache. The bug: the server prefetches, the client receives, the cache is from 24 hours ago because the IndexedDB persister was not invalidated by the buster. The fix is the buster option above, plus a staleTime check in the consumer. The integration test that catches this: load the dashboard offline, wait 60 seconds, come back online, confirm the UI re-renders within staleTime + 5s.
The 50MB IndexedDB ceiling
The third failure is the IndexedDB per-origin ceiling. Most browsers cap IndexedDB at 50MB per origin; the analytics dashboard hit this in late 2025 when the cache grew past 45MB after a 6-month accumulation. The fix is the cache schema versioning above plus a sensible gcTime (5 minutes is the default; 1 hour is what I use on the dashboard). The customer-visible symptom was a slow first-paint after a refresh; the dev-visible symptom was a QuotaExceededError in the browser console.
Where this leaves the codebase
Across the twelve TanStack Query apps I currently ship, every customer-facing route has networkMode configured, an onlineManager heartbeat where the customer base warrants it, dehydrate/HydrationBoundary on the SSR boundary, and IndexedDB or localStorage persistence with schema versioning. The patterns above are the floor, not the ceiling; the ceiling is the wider TanStack Start SSR streaming layer that I have piloted on two non-customer-facing surfaces and will migrate to production in early September 2026.
The full library-by-library state is in the August 2026 mid-month synthesis; the cloud side of the deployment story is in the Cloudflare Workers 2026 guide; the broader TanStack Start implementation is in the TanStack Start deployment guide. The cache invalidation patterns that pair with the network modes here are in the TanStack Query cache invalidation guide; the optimistic update pattern is in the optimistic updates guide; the WebSocket real-time pattern (which uses a different network-mode config) is in the WebSocket guide.
If you want a TanStack Query codebase that ships with these patterns wired in — typed network modes, onlineManager heartbeat, SSR hydration, IndexedDB persistence with schema versioning — TanStack Ship bundles all of it. Pick a server, run the wrangler deploy, and the query layer is already there. The pricing is on the pricing page; the comparison with Shipfast, Makerkit, and the other SaaS boilerplates is on the comparison hub; the broader TanStack Stack choice is on the features page.