Tanstack Query
Set up or fix TanStack Query v5 server state in React apps—including mutations, optimistic updates, infinite queries, and v4→v5 migration errors.
Overview
TanStack Query is an agent skill for the Build phase that configures and debugs React server state with TanStack Query v5, including migrations, mutations, and SSR hydration.
Install
npx skills add https://github.com/jezweb/claude-skills --skill tanstack-queryWhat is this skill?
- TanStack Query v5 coverage: useMutationState, optimistic updates, throwOnError, network/offline mode, infiniteQueryOptio
- Auto-trigger keyword map for discovery (useQuery, gcTime, prefetching, DevTools, SSR hydration)
- Explicit v4→v5 migration fixes: object syntax, gcTime rename, isPending, keepPreviousData removal, initialPageParam
- Production-ready patterns noted for TypeScript strict mode
- Error-boundary and useSuspenseQuery guidance for streaming server components
- Documented as production ready with TypeScript strict mode patterns
- Last updated 2025-10-22 in skill metadata
- Covers v5 APIs including useMutationState and infiniteQueryOptions
Adoption & trust: 2.5k installs on skills.sh; 841 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your React app still uses v4 Query patterns or breaks on gcTime, isPending, and hydration, so data fetching feels fragile and migration errors block shipping.
Who is it for?
Indie React/TypeScript builders migrating to v5 or adding infinite queries, suspense, and offline PWA behavior with agent-guided fixes.
Skip if: Non-React stacks, greenfield projects that want Svelte Query or raw fetch without a cache layer, or backend-only API work with no client integration.
When should I use this skill?
Setting up data fetching, fixing v4→v5 migration errors (object syntax, gcTime, isPending, keepPreviousData), or debugging SSR/hydration issues with streaming server components.
What do I get? / Deliverables
You get v5-correct query keys, QueryClient setup, mutations with optimistic updates, and fixes for streaming SSR hydration so server state stays cached and predictable.
- v5-compliant QueryClient and hook implementations
- Migration fixes for deprecated v4 options and callbacks
- Hydration-safe query setup for SSR or RSC streaming
Recommended Skills
Journey fit
Primary shelf is Build because the skill implements and debugs client-side data fetching and caching in the product UI. Frontend subphase matches React Query patterns, QueryClient setup, suspense, and hydration concerns rather than API server authoring.
How it compares
Skill-backed TanStack Query playbook—not a generic “add React data fetching” chat thread or an MCP data connector.
Common Questions / FAQ
Who is tanstack-query for?
It is for solo builders and small teams building React frontends who need TanStack Query v5 configured correctly and who hit migration or SSR hydration errors during active development.
When should I use tanstack-query?
Use it in Build while setting up QueryClientProvider, writing useQuery/useMutation hooks, fixing v4→v5 errors, or debugging suspense and hydration with streaming server components—before you rely on the same patterns in Ship testing.
Is tanstack-query safe to install?
It is documentation and patterns for client-side libraries without mandating extra credentials; review the Security Audits panel on this Prism page and apply your usual dependency and supply-chain checks for npm packages.
SKILL.md
READMESKILL.md - Tanstack Query
{ "name": "tanstack-query", "description": "Manage server state in React with TanStack Query v5. Covers useMutationState, simplified optimistic updates, throwOnError, network mode (offline/PWA), and infiniteQueryOptions. Use when setting up data fetching, fixing v4→v5 migration errors (object syntax, gcTime, isPending, keepPreviousData), or debugging SSR/hydration issues with streaming server components.", "version": "1.0.0", "author": { "name": "Jeremy Dawes", "email": "jeremy@jezweb.net" }, "license": "MIT", "repository": "https://github.com/jezweb/claude-skills", "keywords": [] } # TanStack Query (React Query) v5 **Status**: ✅ Production Ready **Last Updated**: 2025-10-22 **Production Tested**: Patterns verified with TypeScript strict mode --- ## Auto-Trigger Keywords Claude Code automatically discovers this skill when you mention: ### Primary Keywords - TanStack Query - React Query - useQuery - useMutation - useInfiniteQuery - useSuspenseQuery - QueryClient - QueryClientProvider ### Secondary Keywords - data fetching - server state - caching - staleTime - gcTime - query invalidation - prefetching - optimistic updates - mutations - query keys - query functions - error boundaries - suspense queries - React Query DevTools - v5 migration - v4 to v5 ### Error-Based Keywords - "query callbacks removed" - "cacheTime not found" - "loading status" - "initialPageParam required" - "useQuery is not a function" - "keepPreviousData removed" - "onSuccess removed" - "onError removed" - "object syntax required" - "enabled not available with suspense" - "placeholderData" - "isPending vs isLoading" --- ## What This Skill Does Provides comprehensive knowledge for TanStack Query v5 (React Query) server state management in React applications, including setup, queries, mutations, caching strategies, v4→v5 migration, optimistic updates, infinite queries, and error handling. ### Core Capabilities ✅ QueryClient configuration and setup ✅ useQuery, useMutation, useInfiniteQuery patterns ✅ Optimistic updates and cache management ✅ v4 to v5 migration (all breaking changes) ✅ TypeScript patterns and type safety ✅ Error handling strategies ✅ Caching and refetching strategies ✅ DevTools setup and debugging ✅ Testing patterns with MSW --- ## Known Issues This Skill Prevents | Issue | Why It Happens | Source | How Skill Fixes It | |-------|---------------|---------|-------------------| | **#1: Object Syntax Required** | v5 removed function overloads | [Migration Guide](https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-v5) | Always use `useQuery({ queryKey, queryFn })` | | **#2: Query Callbacks Removed** | onSuccess/onError removed from queries | [v5 Breaking Changes](https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-v5#callbacks-on-usequery-and-queryobserver-have-been-removed) | Use useEffect or move to mutations | | **#3: Status Renamed** | `loading` → `pending` | [v5 Migration](https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-v5#isloading-and-isfetching-flags) | Use `isPending` for initial load | | **#4: cacheTime → gcTime** | Renamed for clarity | [v5 Migration](https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-v5#cachetime-has-been-replaced-by-gctime) | Use `gcTime` instead | | **#5: useSuspenseQuery + enabled** | enabled option not available | [GitHub #6206](https://github.com/TanStack/query/discussions/6206) | Use conditional rendering | | **#6: initialPageParam Required** | v5 requires explicit value | [v5 Migration](https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-v5#new-required-initialPageParam-option) | Always provide `initialPageParam` | | **#7: keepPreviousData Removed** | Replaced with placeholderData | [v5 Migration](https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-v5#removed-keeppreviousdata-in-favor-of-placeholderdata-identity-function) | Use `placeh