Skip to main content
hc
Submit
skillsSource-backed

TanStack Query Data Fetching Skill

Build React server-state workflows with TanStack Query v5, including query keys, QueryClient setup, cache defaults, mutations, invalidation, hydration, retries, and privacy-aware data handling.

by oktofeesh1·added 2026-06-04·
Claude CodeCodexWindsurfGeminiCursorCLI
HarnessClaude CodeCodexWindsurfGeminiCursorCLI
Level:advancedType:generalVerified:validated
Review first — review before installing

Open the source and read safety notes before installing.

Citation facts

Source-backed facts for citing this resource, derived directly from the registry — also available as plain text for AI assistants.

Canonical URL
https://heyclau.de/entry/skills/tanstack-query-data-fetching
Source URLs
https://tanstack.com/query/latest/docs/framework/react/overview, https://github.com/TanStack/query
Package URL
https://github.com/TanStack/query/archive/refs/heads/main.zip
Safety notes
The download URL is TanStack Query's external source archive, not a HeyClaude-packaged skill archive; review source provenance before using it in automated workflows., TanStack Query defaults can refetch stale data on mount, reconnect, and window focus; tune `staleTime`, refetch behavior, and polling for expensive or rate-limited APIs., Failed queries retry by default before surfacing errors. Disable or reduce retries for non-idempotent, quota-sensitive, auth-sensitive, or expensive requests., Mutations can write production data. Require explicit mutation functions, optimistic update rollback logic, and post-success invalidation before trusting assistant-generated changes., Do not put access tokens, raw secrets, full emails, tenant secrets, or large private objects in query keys, console logs, devtools screenshots, or cache persistence keys., Hydration and prefetching can leak user-specific data if caches are shared across requests or serialized into pages without per-user boundaries.
Privacy notes
TanStack Query caches API responses in memory by default and can persist or broadcast cache data when optional persistence plugins are used., Query data can include user records, account IDs, billing details, internal tickets, feature flags, or tenant-scoped objects depending on the API being fetched., React Query Devtools, browser memory snapshots, logs, error reporting, screenshots, and AI transcripts can expose cached response data and query keys., Server-rendered dehydration payloads may serialize cached data into HTML or route payloads; only prefetch data that is safe for that user and request., Redact payload examples before sharing prompts, PR notes, support tickets, or bug reports that involve real query responses.
Platform compatibility
claude-code (native-skill), codex (native-skill), windsurf (native-skill), gemini (native-skill), cursor (adapter), cli (manual-context)
Author
oktofeesh1
Submitted by
oktofeesh1
Claim status
unclaimed
Last verified
2026-06-04

Decision playbook

Review trust signals before you adopt

Signals are present but mixed. Use the checklist below to confirm the source and operational safety for your environment.

Compare context
Selected

0

Current score

86

Baseline

—

Delta

No baseline selected

No major trust-signal divergence detected in the current selection.

Source and provenance checks

Complete

Confirm ownership and provenance before trusting install instructions.

  • Source link availableRequired

    Open the canonical repository and verify ownership.

    Done

  • Source provenance statusRequired

    Marked as source-backed.

    Done

  • Metadata reviewed

    Registry metadata indicates a reviewed listing.

    Done

Safety and privacy checks

Complete

Validate risk disclosures before installation or API wiring.

  • Safety notes presentRequired

    Review the listed safety guidance before running commands.

    Done

  • Privacy notes presentRequired

    Review data handling notes before connecting accounts or secrets.

    Done

  • Trust level risk gateRequired

    Trust level does not block evaluation.

    Done

Package and install checks

Needs review

Check package metadata and artifact integrity signals.

  • Install payload available

    Install or copy payload is available for review.

    Done

  • Package verification flag

    No package verification flag provided.

    Pending

  • Checksum metadata

    No checksum provided for downloaded artifact.

    Pending

Compare-driven decision checks

Needs review

Use compare context to validate trade-offs before adoption.

  • Compare tray has multiple entries

    Add at least one more entry to compare trust differences.

    Pending

  • Baseline comparison available

    No baseline peer selected yet.

    Pending

  • Diverging trust signals identified

    No major trust-signal divergence found.

    Pending

Setup at a glance

Package install

Copy-ready — paste the snippet to get started.

Install command

Provided

Config snippet

Not provided

Copy snippet

Provided

Prerequisites

5 to clear

Platforms

6 listed

Difficulty

74/100

Adoption plan

Balanced adoption plan

Current risk score 16/100. Use staged verification before broader rollout.

Risk 16

Pre-adoption checks

Validate source and review signals before any execution.

  • Confirm source provenanceRequired

    Source URL/provenance metadata is present.

    Done

  • Confirm metadata review state

    Listing has review metadata.

    Done

  • Verify install payload

    Install/config payload exists and can be inspected.

    Done

Security checks

Confirm safety, privacy, and package integrity signals.

  • Review safety notesRequired

    Safety notes are present.

    Done

  • Review privacy notesRequired

    Privacy notes are present.

    Done

  • Verify package integrity metadata

    No package verification/checksum metadata.

    Pending

Rollout

Adopt in controlled steps based on the selected plan.

  • Run in isolated sandbox firstRequired

    Use a constrained sandbox and observe behavior across multiple tasks.

    Pending

  • Roll out graduallyRequired

    Roll out to a small cohort before wider usage.

    Pending

  • Set monitoring and fallback

    Define rollback path and monitor errors after adoption.

    Pending

Evidence readiness

Evidence readiness matrix · balanced

Required evidence gates are covered (5/6 signals complete).

Risk 15

Source provenance

Present

Source repository/provenance is listed.

Required in this preset

Metadata review

Present

Review metadata is present.

Required in this preset

Safety notes

Present

Safety notes are present.

Required in this preset

Privacy notes

Present

Privacy notes are present.

Optional in this preset

Package integrity

Missing

Package integrity metadata is missing.

Optional in this preset

Install payload

Present

Install payload is available.

Required in this preset

Required evidence gates are covered for this preset.

Decision timeline

Decision timeline · balanced

5/6 steps complete with no blocking gaps for this preset.

Risk 14

triage

Confirm source provenanceRequired

Source/provenance metadata is available.

Done

triage

Check metadata review statusRequired

Review metadata is available.

Done

verify

Review safety notesRequired

Safety notes are available.

Done

verify

Review privacy notes

Privacy notes are available.

Done

verify

Validate package integrity metadata

Package integrity metadata is missing.

Pending

rollout

Verify install payload and commandsRequired

Install payload is available.

Done

No required blockers for this timeline preset.

Prerequisite readiness

Prerequisite readiness

5 prerequisites to line up before setup. Have accounts and credentials ready first.

0/5 ready
Account & credentials1Install & runtime2Configuration1General1

Safety & privacy surface

Safety & privacy surface

6 safety and 5 privacy notes across 6 risk areas. Review closely: credentials & tokens, permissions & scopes, network access.

6 areas
  • SafetyNetwork accessThe download URL is TanStack Query's external source archive, not a HeyClaude-packaged skill archive; review source provenance before using it in automated workflows.
  • SafetyGeneralTanStack Query defaults can refetch stale data on mount, reconnect, and window focus; tune `staleTime`, refetch behavior, and polling for expensive or rate-limited APIs.
  • SafetyNetwork accessFailed queries retry by default before surfacing errors. Disable or reduce retries for non-idempotent, quota-sensitive, auth-sensitive, or expensive requests.
  • SafetyData retentionMutations can write production data. Require explicit mutation functions, optimistic update rollback logic, and post-success invalidation before trusting assistant-generated changes.
  • SafetyCredentials & tokensDo not put access tokens, raw secrets, full emails, tenant secrets, or large private objects in query keys, console logs, devtools screenshots, or cache persistence keys.
  • SafetyNetwork accessHydration and prefetching can leak user-specific data if caches are shared across requests or serialized into pages without per-user boundaries.
  • PrivacyData retentionTanStack Query caches API responses in memory by default and can persist or broadcast cache data when optional persistence plugins are used.
  • PrivacyPermissions & scopesQuery data can include user records, account IDs, billing details, internal tickets, feature flags, or tenant-scoped objects depending on the API being fetched.
  • PrivacyExecution & processesReact Query Devtools, browser memory snapshots, logs, error reporting, screenshots, and AI transcripts can expose cached response data and query keys.
  • PrivacyNetwork accessServer-rendered dehydration payloads may serialize cached data into HTML or route payloads; only prefetch data that is safe for that user and request.
  • PrivacyGeneralRedact payload examples before sharing prompts, PR notes, support tickets, or bug reports that involve real query responses.

Safety notes

  • The download URL is TanStack Query's external source archive, not a HeyClaude-packaged skill archive; review source provenance before using it in automated workflows.
  • TanStack Query defaults can refetch stale data on mount, reconnect, and window focus; tune `staleTime`, refetch behavior, and polling for expensive or rate-limited APIs.
  • Failed queries retry by default before surfacing errors. Disable or reduce retries for non-idempotent, quota-sensitive, auth-sensitive, or expensive requests.
  • Mutations can write production data. Require explicit mutation functions, optimistic update rollback logic, and post-success invalidation before trusting assistant-generated changes.
  • Do not put access tokens, raw secrets, full emails, tenant secrets, or large private objects in query keys, console logs, devtools screenshots, or cache persistence keys.
  • Hydration and prefetching can leak user-specific data if caches are shared across requests or serialized into pages without per-user boundaries.

Privacy notes

  • TanStack Query caches API responses in memory by default and can persist or broadcast cache data when optional persistence plugins are used.
  • Query data can include user records, account IDs, billing details, internal tickets, feature flags, or tenant-scoped objects depending on the API being fetched.
  • React Query Devtools, browser memory snapshots, logs, error reporting, screenshots, and AI transcripts can expose cached response data and query keys.
  • Server-rendered dehydration payloads may serialize cached data into HTML or route payloads; only prefetch data that is safe for that user and request.
  • Redact payload examples before sharing prompts, PR notes, support tickets, or bug reports that involve real query responses.

Prerequisites

  • React application or framework route that fetches remote server state.
  • Package manager access to install `@tanstack/react-query`.
  • Inventory of API endpoints, auth requirements, response shapes, mutation side effects, and loading/error UX requirements.
  • Decision on client-only fetching, server rendering, hydration, or router-level prefetching.
  • Approved handling plan for user-specific, tenant-specific, or regulated response data.

Schema details

Install type
package
Reading time
8 min
Difficulty score
74
Troubleshooting
Yes
Breaking changes
No
Source repository stats
Scope
Source repo
Package metadata
Skill and platform metadata
Skill type
general
Skill level
advanced
Verification
validated
Verified at
2026-06-04
Retrieval sources
https://tanstack.com/query/latest/docs/framework/react/overviewhttps://tanstack.com/query/latest/docs/framework/react/quick-starthttps://tanstack.com/query/latest/docs/framework/react/guides/important-defaultshttps://github.com/TanStack/query
Tested platforms
ClaudeCodexWindsurfGeminiCursorGeneric AGENTS
PlatformSupportInstall path
claude-codeNative.claude/skills/<skill-name>/SKILL.md
codexNative.agents/skills/<skill-name>/SKILL.md
windsurfNative.windsurf/skills/<skill-name>/SKILL.md
geminiNative.gemini/skills/<skill-name>/SKILL.md or .agents/skills/<skill-name>/SKILL.md
cursorAdapter.cursor/rules/<skill-name>.mdc
cliManualAGENTS.md or tool-specific context file
Full copyable content
# Trigger
"Apply the TanStack Query data fetching skill to this React app."

# Required output
1) Server-state surface and current fetching inventory
2) QueryClient, provider, query key, and cache-default plan
3) useQuery/useMutation/invalidation implementation steps
4) Retry, hydration, devtools, and privacy/safety checks

About this resource

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

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.

#tanstack-query#react-query#react#server-state#data-fetching

Source citations

Add this badge to your README

Show that TanStack Query Data Fetching Skill is listed on HeyClaude. Paste this Markdown into your README — it renders the badge and links back to this page.

Listed on HeyClaude
[![Listed on HeyClaude](https://heyclau.de/badge/skills/tanstack-query-data-fetching.svg)](https://heyclau.de/entry/skills/tanstack-query-data-fetching)

How it compares

TanStack Query Data Fetching Skill side by side with 2 alternatives on trust, install, platform support, and disclosed safety notes — all from reviewed registry metadata.

3 trust signals differ across this comparison (Package trust, Source provenance, Submitter).

Next steps differ across entries — use the actions in the table below to copy install commands and source links per resource.

Field
TanStack Query Data Fetching Skill

Build React server-state workflows with TanStack Query v5, including query keys, QueryClient setup, cache defaults, mutations, invalidation, hydration, retries, and privacy-aware data handling.

Open dossier
Prompt Caching Cost Audit Capability Pack Skill

Expert prompt caching cost audit capability pack for measuring Claude Code cache hit rates, identifying cache invalidation triggers, and reducing token spend from CLAUDE.md edits, model switches, and startup load changes.

Open dossier
tRPC Type-Safe API Builder Skill

Build end-to-end type-safe APIs with tRPC and TypeScript, eliminating code generation and runtime bloat for full-stack applications. tRPC provides end-to-end type safety without code generation, schema stitching, or serialization layers - delivering a lighter, more intuitive developer experience than REST or GraphQL.

Open dossier
Next stepsDiffers
Open dossierAPI JSONOpen LLMOpen sourceNewsletterClaim listing
Open dossierAPI JSONOpen LLMOpen sourceNewsletterClaim listing
Open dossierAPI JSONOpen LLMOpen sourceNewsletterClaim listing
Trust
Review statusReviewedMaintainer reviewedReviewedMaintainer reviewedReviewedMaintainer reviewed
Package trustDiffersPackage not verifiedPackage not verifiedPackage verified2025-10-16
Source provenanceDiffersSource-backedSubmission linkedSource submissionNo submission link
SubmitterDiffersoktofeesh1kiannidev—
Install riskReview firstReview firstLow risk
Notes Safety ✓ Privacy ✓ Safety ✓ Privacy ✓ Safety ✓ Privacy ✓
Brand———
Categoryskillsskillsskills
SourceSource-backedSource-backedFirst-party
Authoroktofeesh1kiannidevJSONbored
Added2026-06-042026-06-142025-10-16
Platforms
Claude CodeCodexWindsurfGeminiCursorCLI
Claude CodeCodexWindsurfGeminiCursorCLI
Claude CodeCodexWindsurfGeminiCursorCLI
Harness
Claude CodeCodexWindsurfGeminiCursorCLI
Claude CodeCodexWindsurfGeminiCursorCLI
Claude CodeCodexWindsurfGeminiCursorCLI
Source repo———
Safety notes✓The download URL is TanStack Query's external source archive, not a HeyClaude-packaged skill archive; review source provenance before using it in automated workflows. TanStack Query defaults can refetch stale data on mount, reconnect, and window focus; tune `staleTime`, refetch behavior, and polling for expensive or rate-limited APIs. Failed queries retry by default before surfacing errors. Disable or reduce retries for non-idempotent, quota-sensitive, auth-sensitive, or expensive requests. Mutations can write production data. Require explicit mutation functions, optimistic update rollback logic, and post-success invalidation before trusting assistant-generated changes. Do not put access tokens, raw secrets, full emails, tenant secrets, or large private objects in query keys, console logs, devtools screenshots, or cache persistence keys. Hydration and prefetching can leak user-specific data if caches are shared across requests or serialized into pages without per-user boundaries.✓Cost reduction must not remove safety-critical instructions from CLAUDE.md or skills without explicit review. Aggressive cache optimization that strips needed context can increase mistake rates and rework cost. Model switches invalidate prompt caches; frequent alias changes can silently increase spend. This skill recommends configuration changes; it must not edit CLAUDE.md, skills, or MCP config without explicit user approval.✓Installs server/client packages (@trpc/server, @trpc/client, zod) and runs an API server; review procedures, auth middleware, and exposed routers before deploying.
Privacy notes✓TanStack Query caches API responses in memory by default and can persist or broadcast cache data when optional persistence plugins are used. Query data can include user records, account IDs, billing details, internal tickets, feature flags, or tenant-scoped objects depending on the API being fetched. React Query Devtools, browser memory snapshots, logs, error reporting, screenshots, and AI transcripts can expose cached response data and query keys. Server-rendered dehydration payloads may serialize cached data into HTML or route payloads; only prefetch data that is safe for that user and request. Redact payload examples before sharing prompts, PR notes, support tickets, or bug reports that involve real query responses.✓Cost audits may expose repository names, team usage patterns, and internal project structure from CLAUDE.md and skill inventories. Usage dashboards and `/cost` output can include account identifiers that should not be pasted into public issues. Public audit summaries should describe invalidation categories and recommended actions, not full settings dumps.✓tRPC procedures read and persist user-supplied input and use auth context/tokens; validate inputs with zod, keep secrets in environment variables, and review what each procedure stores or logs.
Prerequisites
  • React application or framework route that fetches remote server state.
  • Package manager access to install `@tanstack/react-query`.
  • Inventory of API endpoints, auth requirements, response shapes, mutation side effects, and loading/error UX requirements.
  • Decision on client-only fetching, server rendering, hydration, or router-level prefetching.
  • An active or recent Claude Code session with observed cost increase or low cache reuse.
  • Access to cost or usage indicators such as `/cost`, billing dashboards, or session token summaries when available.
  • Redacted view of CLAUDE.md, skills, MCP config, and settings changed recently in the workspace.
  • Knowledge of model alias or version switches during the affected session window.
  • Node.js 18+
  • TypeScript 5.0+
  • @trpc/server ^10.0.0
  • @trpc/client ^10.0.0
Install
pnpm add @tanstack/react-query
—
npm install @trpc/server @trpc/client @trpc/react-query zod
Config———
Citations
ClaimUnclaimedUnclaimedUnclaimed
Open 3 picks in the interactive comparison tool

Signals

Loading live community signals…

More like this, weekly

A short, calm digest of reviewed Claude resources. Unsubscribe any time.