TanStack Query Data Fetching Skill

Knowledge Freshness

This skill is based on TanStack Query React v5 docs and the official TanStack/query repository reviewed on 2026-06-04. The current React docs describe TanStack Query as a library for fetching, caching, synchronizing, and updating server state, with core React setup through QueryClient, QueryClientProvider, useQuery, useMutation, and query invalidation.

Retrieval Sources

• https://tanstack.com/query/latest/docs/framework/react/overview
• https://tanstack.com/query/latest/docs/framework/react/quick-start
• https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults
• https://github.com/TanStack/query

Prefer the live TanStack Query docs and official repository over model memory for package names, v5 API details, default cache behavior, retry behavior, hydration APIs, devtools, and framework-specific guidance.

Scope Note

Use this skill for React applications that need client-side or hydrated server-state management with TanStack Query. It is not a replacement for API design, authorization policy, database transactions, or backend data-consistency review.

Core Workflow

1. Inventory existing data fetching: route loaders, server components, effects, custom hooks, global stores, tRPC hooks, REST clients, GraphQL clients, and mutation paths.
2. Separate server state from client state. Use TanStack Query for remote, asynchronous, shareable, cacheable data; keep local UI state outside query cache unless it is derived from server responses.
3. Install @tanstack/react-query and add one stable QueryClient plus QueryClientProvider at the correct app boundary.
4. Define query keys as stable arrays that identify data scope without exposing secrets or unnecessary personal data.
5. Wrap each fetch path in a typed query function with explicit error handling, request cancellation behavior where relevant, and authentication assumptions documented.
6. Tune important defaults before broad rollout: staleTime, gcTime, retries, refetch-on-window-focus, refetch-on-reconnect, and polling.
7. Convert writes to useMutation with explicit mutation functions, invalidation, optimistic updates only when rollback is clear, and user-facing error states.
8. Plan pagination, infinite queries, dependent queries, and prefetching only after the base query key and cache invalidation model are stable.
9. For SSR, streaming, or framework prefetching, confirm per-request cache isolation and only dehydrate data that is safe for the current user.
10. Add validation evidence: loading state, error state, cache hit behavior, invalidation after mutation, retry behavior, and privacy review.

Required Inputs

• React framework, routing layer, package manager, and render mode.
• API endpoints, request clients, auth/session model, and response schemas.
• Query candidates with owner, scope, freshness requirements, and expected invalidation triggers.
• Mutation paths, side effects, rollback expectations, and user notification requirements.
• SSR/hydration/prefetch requirements and data that must never be serialized into HTML or shared caches.
• Rate limits, API quotas, and retry tolerance for each remote service.

Production Rules

• Do not use TanStack Query as a catch-all global store. Keep it focused on server state.
• Make query keys stable, scoped, and non-secret. Treat them as observable application metadata.
• Set staleTime deliberately for expensive, slow, or rate-limited endpoints.
• Review retry defaults for every endpoint that can trigger noisy logs, quota burn, lockouts, or repeated auth failures.
• Use invalidation after mutations instead of hoping cached lists refresh by accident.
• Do not use optimistic updates unless there is a clear rollback path and a user-visible failure state.
• Keep Devtools out of production unless intentionally enabled and reviewed.
• Isolate per-request query clients for server rendering and hydration.

Compatibility

Native

• Claude Code / Claude: use as a reusable Agent Skill for React data fetching implementation and review.
• Codex/OpenAI workflows: use as SKILL.md-style instructions while editing React, Next.js, Remix, TanStack Router, Vite, or SPA codebases.

Manual Adaptation

• Cursor, Windsurf, Gemini, and Generic AGENTS files: adapt the workflow, production rules, and output contract into project-level frontend rules.

Output Contract

1. Source evidence: TanStack Query docs and repository reviewed, with date.
2. Data inventory: existing fetches, query candidates, mutations, response sensitivity, and render mode.
3. Implementation plan: QueryClient, provider placement, query keys, query functions, mutations, invalidation, and cache defaults.
4. Safety/privacy review: query keys, retries, devtools, persistence, hydration, logs, and real-user data handling.
5. Validation checklist: loading, error, success, cache hit, background refetch, mutation invalidation, retry behavior, and SSR/hydration boundaries.

Duplicate And Source Review

Current HeyClaude content mentions React Query inside adjacent tRPC, React, and rule entries, and the web app itself uses @tanstack/react-query, but there is no dedicated TanStack Query or React Query skill entry. This skill is scoped to the official TanStack Query React workflow and is backed by the current TanStack docs and official repository.

Troubleshooting

Issue: The same request fires repeatedly

Fix: Check query key stability, component remounting, staleTime, refetch-on-window-focus, polling, and whether the query function is recreated with unstable inputs.

Issue: A mutation succeeds but the UI still shows old data

Fix: Invalidate or update the exact affected query keys in onSuccess. Confirm the list/detail keys use the same scope and tenant identifiers.

Issue: Sensitive user data appears in Devtools or screenshots

Fix: Disable Devtools for shared environments, redact query data before reporting issues, and keep secrets or private payloads out of query keys.

Issue: SSR output leaks another user's data

Fix: Create a per-request QueryClient, avoid cross-request cache reuse, and only dehydrate data that belongs to the current authenticated user.

Issue: Failed requests burn API quota

Fix: Reduce retry, customize retryDelay, avoid polling for the endpoint, and surface auth/rate-limit failures quickly instead of silently retrying them.