tanstack-query-expert

Implements TanStack Query data fetching, caching, mutations, and Next.js SSR hydration patterns.

Updated Aug 11, 2026
One-click install
npx skills add https://github.com/DucCuong159/Realtime-chatapp --skill tanstack-query-expert-duccuong159
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: tanstack-query-expert
Source: https://github.com/DucCuong159/Realtime-chatapp/tree/main/.agent/skills/tanstack-query-expert
Command: npx skills add https://github.com/DucCuong159/Realtime-chatapp --skill tanstack-query-expert-duccuong159

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Managing asynchronous server state in React with raw useEffect and useState leads to duplicated requests, stale caches, and missing loading or error states. This Skill provides production-grade TanStack Query patterns for declarative data fetching, cache invalidation, optimistic updates, and SSR hydration. ## Core Features & Use Cases - Query & Mutation Patterns: Custom hook abstractions, array-based query key factories, staleTime/gcTime configuration, and cache invalidation after mutations. - Optimistic Updates: Instant UI feedback with onMutate cache snapshots, rollback on error, and refetch on settle. - Next.js App Router Integration: QueryClientProvider setup, server-side prefetchQuery, and HydrationBoundary dehydration for zero-request client hydration. - Use Case: Refactor a component that fetches user data with useEffect into a typed useUser custom hook with a 5-minute staleTime, then add an optimistic update mutation for editing the user profile. ## Quick Start Ask the assistant to refactor a React component that fetches data with useEffect into a TanStack Query custom hook with proper query keys and cache invalidation.

Frequently Asked Questions about tanstack-query-expert

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fetch data with TanStack Query in React?

Wrap useQuery in a custom hook with an array-based queryKey and an async queryFn that throws on non-OK responses. Set staleTime to control background refetching and use the enabled option for dependent queries.

How to do optimistic updates with React Query mutations?

Use the onMutate callback to cancel outgoing queries, snapshot the previous cache with getQueryData, and apply the new value via setQueryData. On error, restore the snapshot from context, and always invalidate the query in onSettled.

Does TanStack Query work with Next.js App Router?

Yes. Create a client Providers component with QueryClientProvider, then prefetch data in Server Components using a new QueryClient and pass dehydrated state through HydrationBoundary so client useQuery reads from cache without refetching.

What is the difference between staleTime and gcTime?

staleTime controls when cached data becomes stale and triggers a background refetch, while gcTime controls how long inactive data stays in memory after components unmount. Setting gcTime lower than staleTime deletes data before it becomes stale.

Why does TanStack Query refetch on every component mount?

The default staleTime is 0, so data is considered stale immediately and refetches on every mount. Set a global staleTime in QueryClient defaultOptions, such as 60 seconds, to prevent unnecessary background requests.