TanStack Query: Query Invalidation

Control cache freshness with invalidateQueries, staleTime, gcTime, and refetch strategies

When to Use

• Refreshing data after a mutation without a full page reload
• Tuning how long cached data is considered fresh before background refetching
• Controlling when stale queries are garbage collected from memory
• Deciding between active refetch (immediate) and background refetch (on next mount/focus)

Instructions

1. Call

   queryClient.invalidateQueries({ queryKey })

   after mutations to mark related queries as stale and trigger refetch.
2. Use hierarchical keys for broad invalidation —

   { queryKey: ['posts'] }

   invalidates all queries whose key starts with

   ['posts']

   .
3. Set

   refetchType: 'active'

   (default) to refetch only currently mounted queries; use

   refetchType: 'all'

   to refetch mounted and unmounted cached queries; use

   refetchType: 'none'

   to mark stale without refetching.
4. Configure

   staleTime

   in

   queryOptions

   or globally in

   QueryClient

   defaults — this is how long data is considered fresh (no background refetch on mount).
5. Configure

   gcTime

   (formerly

   cacheTime

   ) to control how long inactive query data stays in memory — defaults to 5 minutes.
6. Use

   queryClient.refetchQueries()

   when you want immediate refetch without going through the stale check.
7. Prefer

   invalidateQueries

   over

   refetchQueries

   for post-mutation refresh — invalidation is more composable with

   staleTime

   .

// Global defaults in QueryClient setup
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60 * 1000, // 1 minute — queries fresh for 60s after fetch
      gcTime: 5 * 60 * 1000, // 5 minutes — inactive data stays in memory for 5min
      retry: 2, // retry failed requests twice
    },
  },
});

// Post-mutation invalidation patterns
function useCreatePost() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: createPost,
    onSuccess: () => {
      // Invalidate all post lists — refetches active ones immediately
      queryClient.invalidateQueries({ queryKey: postKeys.lists() });
    },
  });
}

// Selective invalidation by refetchType
queryClient.invalidateQueries({
  queryKey: postKeys.lists(),
  refetchType: 'active', // only refetch if component is currently mounted
});

// Targeted invalidation — only invalidate a specific detail
queryClient.invalidateQueries({
  queryKey: postKeys.detail('abc-123'),
  exact: true, // match exact key, not prefix
});

Details

TanStack Query maintains a lifecycle for each cached query:

fresh

→

stale

→

inactive

→

garbage collected

.

staleTime

: While data is

fresh

, queries do not refetch on component mount or window focus. Once data becomes

stale

(after

staleTime

ms), TanStack Query triggers a background refetch on the next mount or focus event. Default is

0

— data is always stale immediately after fetching.

gcTime

: When a query has no active subscribers (no component mounted that uses it), TanStack Query starts a garbage collection timer. After

gcTime

ms, the cached data is removed. If the query mounts again before GC, it still returns the stale cached data immediately while refetching in the background.

Invalidation vs refetch timing:

• invalidateQueries

  with

  refetchType: 'active'

  : marks stale + immediately refetches mounted queries. Non-mounted queries refetch next time they mount.

• invalidateQueries

  with

  refetchType: 'none'

  : marks stale only. Next mount or focus triggers refetch.

• refetchQueries

  : forces immediate refetch regardless of staleTime.

exact: true

vs prefix matching: Without

exact

,

queryKey: ['posts']

matches

['posts', 'list', {}]

,

['posts', 'detail', '1']

, etc. With

exact: true

, it only matches the exact key

['posts']

. Use prefix matching for broad post-mutation invalidation; use

exact

when only a specific entry should be invalidated.

Combining staleTime with invalidation: Setting

staleTime: Infinity

is common for reference data that never changes at runtime (static lists, config). Explicitly invalidate these on admin mutations rather than relying on time-based staleness.

Source

https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.