tanstack-query
TanStack Query v5 handles server state management in React through data fetching, caching, and mutation patterns. Learn QueryClient setup, hook usage with the v5 object syntax, and common migration issues from v4.
TanStack Query v5 provides React hooks for managing server state, data fetching, and caching with QueryClient.
AI-generated summary based on this skill's SKILL.md
Install
secondsky/claude-skills/tanstack-query · repository language: TypeScript
git clone https://github.com/secondsky/claude-skills
cp -r claude-skills/plugins/tanstack-query/skills/tanstack-query ~/.claude/skills/tanstack-queryFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I set up TanStack Query v5 in a React project?
TanStack Query v5 requires wrapping your app with QueryClientProvider. First, create a QueryClient instance, then wrap your component tree with <QueryClientProvider client={queryClient}>. Configure cache behavior via QueryClient defaults—set staleTime and gcTime (formerly cacheTime) to control when data becomes stale and when it's garbage collected. Install @tanstack/react-query and set up devtools with @tanstack/react-query-devtools for debugging.
What are the key breaking changes migrating from React Query v4 to TanStack Query v5?
TanStack Query v5 renamed cacheTime to gcTime and changed hook option syntax to an object-based format. The isPending flag replaces isLoading for distinguishing pending states. Ensure all queryKey definitions follow array syntax consistently. Review your useQuery and useMutation calls—v5 requires explicit option objects rather than positional parameters. Update imports from react-query to @tanstack/react-query.
How do I implement data fetching and caching with useQuery and useMutation?
TanStack Query useQuery handles fetching and caching: pass a queryKey array and queryFn. Data automatically caches based on staleTime and gcTime settings. useMutation manages side effects like POST/PUT requests. After mutations, call queryClient.invalidateQueries({queryKey: [...]}) to refresh related data. Use the onSuccess callback to trigger invalidations or optimistic updates immediately after mutation completion.
What's the difference between isPending and isLoading in TanStack Query v5?
TanStack Query v5 uses isPending to indicate any pending request state, replacing v4's isLoading. isPending returns true during initial fetch and refetches. Use isPending for general loading UI. The isFetching flag separately tracks background refetches, useful for showing subtle indicators while cached data remains visible. This separation lets you display stale data with a refresh indicator instead of full loading states.
How do I prevent request waterfalls and implement prefetching in TanStack Query v5?
TanStack Query prefetching uses queryClient.prefetchQuery() to load data before queries run. Set enabled: false on dependent queries, then enable them once parent data loads. Use useQuery with select to transform data without refetching. For infinite scroll, useInfiniteQuery with getNextPageParam handles pagination. Prefetch next pages during scroll to avoid waterfalls and provide seamless pagination.
How do I handle stale data and invalidation errors in TanStack Query v5?
Configure staleTime to control when cached data becomes stale—higher values reduce refetches. Use queryClient.invalidateQueries() after mutations to refresh specific queries by key. Set gcTime appropriately; too low causes unnecessary refetches, too high wastes memory. For error handling, use throwOnError in query options or catch errors in onError callbacks. Monitor background refetch indicators with isFetching to show users when data updates.
SKILL.md
rendered from the published skill — quoted content, verbatim
TanStack Query (React Query) v5
Status: Production Ready ✅ Last Updated: 2025-12-09 Dependencies: React 18.0+ (18.3+ recommended), TypeScript 4.9+ (5.x
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 15 files
plugins/tanstack-query/skills/tanstack-query/SKILL.md
plugins/tanstack-query/skills/tanstack-query/assets/example-template.txt
plugins/tanstack-query/skills/tanstack-query/examples/README.md
plugins/tanstack-query/skills/tanstack-query/examples/basic-graphql-request.tsx
plugins/tanstack-query/skills/tanstack-query/examples/basic.tsx
plugins/tanstack-query/skills/tanstack-query/examples/default-query-function.ts
plugins/tanstack-query/skills/tanstack-query/examples/infinite-scroll.tsx
plugins/tanstack-query/skills/tanstack-query/examples/nextjs-app-router.tsx
plugins/tanstack-query/skills/tanstack-query/examples/optimistic-update.tsx
plugins/tanstack-query/skills/tanstack-query/examples/pagination.tsx
plugins/tanstack-query/skills/tanstack-query/examples/prefetching.tsx
plugins/tanstack-query/skills/tanstack-query/examples/react-native.tsx
plugins/tanstack-query/skills/tanstack-query/examples/suspense.tsx
plugins/tanstack-query/skills/tanstack-query/references/advanced-setup.md
plugins/tanstack-query/skills/tanstack-query/references/best-practices.md