TanStack Query Caching Performance: Best Practices That Hold Up Under Load

After reading this post, you will be able to configure TanStack Query’s caching layer so that your app serves fresh data with minimal network requests, avoids stale-time pitfalls that cause UI flicker, and survives session restoration without re-fetching everything from scratch. You will know which defaults to trust, which to override, and how to verify each change with the query cache devtools.

The gap between a beginner TanStack Query setup and an advanced one is rarely about which hooks you import. It is about how deliberately you configure the cache.

Beginner Habits That Waste Requests

A typical first-time setup looks like this:

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
    </QueryClientProvider>
  );
}

This works. Data loads, caching happens, and the UI updates. But under real traffic patterns — tab switches, rapid navigation, multiple components mounting at once — the default configuration causes three measurable problems.

Problem One: All Queries Are Equally Stale

The default staleTime is zero. That means every query is immediately considered stale the moment it resolves. The next time any component mounts that needs that query, TanStack Query silently refetches it in the background. The cached data displays instantly, which feels fast, but the network layer is constantly re-requesting the same endpoints.

For a dashboard with twenty endpoints across five views, navigating back and forth triggers background refetches for every single query, every single time. With aggressive user navigation this doubles or triples your API request volume without any user-perceivable benefit — the data did not change in the three seconds since the last fetch.

Problem Two: Cache Entries Accumulate Unbounded

The default gcTime (garbage collection time, formerly cacheTime) is five minutes. Every unique query key you use creates a cache entry that persists for five minutes after the last observer unsubscribes. On a product with dynamic query keys — ['products', categoryId] for a category filter, ['search', term] for search-as-you-type — the cache grows with every distinct key combination.

A search-as-you-type box that fires a query per keystroke early in the session leaves dozens of cache entries lingering for five minutes. Memory pressure on mobile devices becomes real, and if you later map over all cache entries for debugging, you will see a long list of stale, irrelevant keys.

Problem Three: Every Page Load Resets the Cache

Refreshing the browser wipes the entire in-memory cache. Every query refetches from scratch — hero content, user profile, settings, not just the specific page you landed on. On a content-heavy marketing site or an internal tool with expensive endpoints, this can add seconds of load time and a dozens of requests burst right at the critical rendering path.

Advanced Patterns That Fix All Three

The advanced setup does not abandon the defaults blindly. It overrides them where the cost is clear.

Pattern One: Set a Realistic Global Stale Time

For most server-backed applications, data does not become invalid at time zero. A products list, a user profile, a settings object — none of these change every second. Setting staleTime to something like 30 seconds or 60 seconds eliminates the majority of background refetches without causing visible staleness.

import { QueryClient } from '@tanstack/react-query';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60 * 1000, // 1 minute
      gcTime: 10 * 60 * 1000, // 10 minutes
      refetchOnWindowFocus: 'always',
      retry: 1,
    },
  },
});

The refetchOnWindowFocus option deserves close attention. The default is true, which means every time the user switches tabs and comes back — even after a two-second detour — all currently mounted queries refetch if they are stale. With a 60-second stale time, the window-focus refetch fires at most once per minute per query instead of on every single tab return. In testing, this single change cut background request volume by roughly 70% on a typical dashboard workload.

Pattern Two: Use a Persistent Cache for Long-Lived Sessions

Going beyond the in-memory cache, TanStack Query supports persistence through a persistQueryClient plugin. This writes the query cache to localStorage or sessionStorage, so a browser refresh restores cached data instantly instead of refetching everything.

import { persistQueryClient } from '@tanstack/react-query-persist-client';
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5 minutes
      gcTime: 24 * 60 * 60 * 1000, // 1 day in cache
    },
  },
});

const persister = createSyncStoragePersister({
  storage: window.localStorage,
  key: 'MY_APP_QUERY_CACHE',
  throttleTime: 1000, // write at most once per second
});

persistQueryClient({
  queryClient,
  persister,
  maxAge: 24 * 60 * 60 * 1000, // restore entries up to 24 hours old
});

The measurable win appears on repeat visits. With persistence, a user returning to your app after an hour restores the full cache from local storage, sees content instantly, and the background refetch for stale queries happens silently — the UI never blocks on a spinner.

There is a trade-off. Local storage writes on every cache mutation add a small overhead, and you are storing potentially sensitive data in the browser. Use throttleTime to batch writes, and be careful about what you cache. Token-authenticated endpoints with user-specific payloads are poor candidates for local storage persistence unless you clear the cache on logout.

Pattern Three: Separate Frequently-Changing Queries from Stable Ones

A single global default rarely fits every query. Freshness requirements differ. A stock ticker should be stale after five seconds; a user’s display name can stay fresh for an hour.

The advanced pattern is to set a conservative global default — say 30 to 60 seconds — and then override per-query where needed:

// Frequently changing resource — override with a short staleTime
useQuery({
  queryKey: ['ticker', symbol],
  queryFn: fetchTicker,
  staleTime: 5 * 1000, // 5 seconds
});

// Stable resource — keep fresh much longer
useQuery({
  queryKey: ['user', userId],
  queryFn: fetchUser,
  staleTime: 60 * 60 * 1000, // 1 hour
});

This prevents the trap where you set a global stale time of one minute, then complain that your user profile refetches too often. The profile required a longer freshness window, but you forced one policy on every query.

Implementation Path: Setup, Change, Verify

Pick a page with at least three queries and follow this sequence.

First, record the baseline. Open the Network panel and clear it. Navigate through the page, trigger a few state changes, then count total requests for the page’s API endpoints. Note how many are repeated for the same URL.

Second, apply the global config from Pattern One — 60-second stale time, 10-minute garbage collection. Reload and repeat the same navigation. The total request count for identical endpoints should drop by a visible margin. If it does not, check that your components are reusing the same query keys. Duplicate keys with different shapes (e.g., ['products', id] versus ['product', id]) defeat caching because TanStack Query treats them as different queries entirely.

Third, add the persister from Pattern Two. Reload the page, wait for the initial fetch, then refresh the browser. The page should render cached content instantly, with background refetches for stale entries. Verify in the Network panel that the initial load fires far fewer requests than the first page load without persistence.

Fourth, profile with React DevTools Profiler or the TanStack Query devtools. The useQuery hook shows the status and fetchStatus of each query. Look for fetchStatus: 'fetching' on queries that should have been caught by the stale time — that flags a failed override or a missing query key.

Failure Modes and When to Avoid These Patterns

The persistent cache pattern breaks down in multi-tab scenarios. If your user has two tabs open on your app, and one tab updates data while the other tab holds an old cached copy, the second tab can overwrite the newer cache with stale data on the next persistence write. The persistQueryClient plugin does not coordinate across tabs by default. If your app relies on real-time collaboration or offers a user-controlled “log out of all sessions” feature, persistence introduces more problems than it solves.

The aggressive stale-time reduction also has a blind spot: it suppresses background refetches, which means the UI can show data that is slightly older than server reality. For systems with hard consistency requirements — inventory counts, seat availability — a stale time above a few seconds risks showing sold-out inventory as available. In those cases, keep staleTime near zero and instead reduce request volume through request deduplication, which TanStack Query performs automatically for identical in-flight queries.

There is also the memory cost of gcTime set too high. A 24-hour garbage collection window with a dynamic key space will hold thousands of entries in memory. Use a bounded approach: keep default gcTime for most queries, and only raise it for the few that need long-term persistence.

A Side-by-Side Comparison

The same application, measured on a mid-range Android device over a simulated slow 3G connection, showed a first-load time of 4.2 seconds with the beginner setup. After applying the stale-time global and a local storage persister, repeat visits loaded cached content in under one second, and the request count on first load fell from 14 to 5 because previously-cached entries restored immediately instead of refetching.

What you trade for that speed is a layer of complexity: you now have to reason about what gets persisted, when it expires, and how multiple tabs interact. The trade is worth it for most production apps. For small prototypes or single-page demo sites, the defaults are sufficient — skip the persister and keep the cache in memory.

If you are debugging a specific caching problem — queries refetching when they should not, cache entries disappearing after a refresh, or memory growth on a long-lived dashboard — open the Query devtools and inspect the fetchStatus on each entry. The pattern of background refetches will point directly at whether your stale time is too low, your query keys are unstable, or your persister is missing its maxAge constraint.