Execution contract
- Use when
- Use when a team needs explicit freshness, background-refetch, and collection rules for each data type.
- Avoid when
- Do not inflate staleTime to hide incorrect query keys or duplicate QueryClient instances.
- Preconditions
- Record change frequency, acceptable staleness, explicit invalidation events, and offline needs.
- Verification
- Use controlled time to verify fresh, stale, and inactive transitions, including focus and reconnect behavior.
- Failure mode
- For unexpected refetches inspect default staleness and focus triggers; for frozen data check accidental static policy.
- Security
- Clear user-scoped cache on logout or permission changes to avoid showing previous-user data in shared sessions.
Two timelines
staleTime controls when stale-state refetching is allowed; gcTime only controls retention after a query has no observers. A long gcTime is not a freshness policy, and default background refetching does not mean the cache failed.
Shared contract
Use queryOptions to co-locate queryKey, queryFn, and time policy. Reuse the same function from loaders, useQuery, prefetchQuery, and setQueryData to preserve inference and prevent key drift.
import { queryOptions } from '@tanstack/react-query'
export const issuesOptions = queryOptions({
queryKey: ['issues', 'list'] as const,
queryFn: getIssues,
staleTime: 30_000,
gcTime: 5 * 60_000,
})Selection rule
Choose staleTime from acceptable server age, tolerance for background refresh, and whether this client writes the data. Use Infinity only when automatic refetch is truly unnecessary, and still invalidate precise resource keys after relevant mutations.