TanStack Query Config Builder

TanStack Query is an async state management library for React (and other frameworks). It handles fetching, caching, background updates, and synchronization of server state. Instead of manually managing loading/error/data state with useState and useEffect, you call useQuery and let the library handle everything.

staleTime is how long (in ms) fetched data is considered fresh. During this window, React Query won't refetch the data — it serves the cached version. After staleTime expires, data is considered stale, and React Query will refetch when the query is re-used (e.g., on window focus or component mount).

gcTime (garbage collection time) is how long inactive query data stays in memory after all components using it unmount. Once gcTime expires, the cache entry is removed. gcTime should always be ≥ staleTime. Default is 5 minutes. Setting it to Infinity keeps data in memory until page reload.

initialData is treated as real data — it counts as a successful cache entry, respects staleTime, and won't trigger a background fetch if still fresh. placeholderData is UI-only — it's shown while the query loads but never persisted to the cache. Use initialData for SSR-hydrated data, placeholderData for skeleton/preview content.

retry controls how many times React Query retries a failed request before marking the query as error state. Default is 3. Each retry uses exponential backoff (retryDelay). Set to false to disable retries (useful for user-input queries where immediate feedback is needed).

Create a QueryClient instance outside your component tree and pass it to QueryClientProvider at your app root. You can access it with useQueryClient() hook inside components for manual invalidation, prefetching, or setting cached data. For SSR/Next.js, create a new QueryClient per request to avoid shared state between users.