TanStack Query v5 performance optimization for data fetching, caching, mutations, and query patterns. This skill should be used when using useQuery, useMutation, queryClient, prefetch patterns, or TanStack Query caching. This skill does NOT cover generating query hooks from OpenAPI (use orval skill) or mocking API responses in tests (use test-msw skill).
Comprehensive performance optimization guide for TanStack Query v5 applications. Contains 40 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
Reference these guidelines when:
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Query Key Structure | CRITICAL | tquery- |
| 2 | Caching Configuration |
| CRITICAL |
cache- |
| 3 | Mutation Patterns | HIGH | mutation- |
| 4 | Prefetching & Waterfalls | HIGH | prefetch- |
| 5 | Infinite Queries | MEDIUM | infinite- |
| 6 | Suspense Integration | MEDIUM | suspense- |
| 7 | Error & Retry Handling | MEDIUM | error- |
| 8 | Render Optimization | LOW-MEDIUM | render- |
tquery-key-factories - Use centralized query key factoriestquery-hierarchical-keys - Structure keys from generic to specifictquery-always-arrays - Always use array query keystquery-serializable-objects - Use serializable objects in keystquery-options-pattern - Use queryOptions for type-safe sharingtquery-colocate-keys - Colocate query keys with featurescache-staletime-gctime - Understand staleTime vs gcTimecache-global-defaults - Configure global defaults appropriatelycache-placeholder-vs-initial - Use placeholderData vs initialData correctlycache-invalidation-precision - Invalidate with precisioncache-refetch-triggers - Control automatic refetch triggerscache-enabled-option - Use enabled for conditional queriesmutation-optimistic-updates - Implement optimistic updates with rollbackmutation-invalidate-onsettled - Invalidate in onSettled, not onSuccessmutation-cancel-queries - Cancel queries before optimistic updatesmutation-setquerydata - Use setQueryData for immediate cache updatesmutation-avoid-parallel - Avoid parallel mutations on same dataprefetch-avoid-waterfalls - Avoid request waterfallsprefetch-on-hover - Prefetch on hover for perceived speedprefetch-in-queryfn - Prefetch dependent data in queryFnprefetch-server-components - Prefetch in Server Componentsprefetch-flatten-api - Flatten API to reduce waterfallsinfinite-max-pages - Limit infinite query pages with maxPagesinfinite-flatten-pages - Flatten pages for renderinginfinite-refetch-behavior - Understand infinite query refetch behaviorinfinite-loading-states - Handle infinite query loading states correctlysuspense-use-suspense-hooks - Use Suspense hooks for simpler loading statessuspense-error-boundaries - Always pair Suspense with Error Boundariessuspense-parallel-queries - Combine Suspense queries with useSuspenseQueriessuspense-boundaries-placement - Place Suspense boundaries strategicallyerror-retry-config - Configure retry with exponential backofferror-conditional-retry - Use conditional retry based on error typeerror-global-handler - Use global error handler for common errorserror-display-patterns - Display errors appropriatelyerror-throw-on-error - Use throwOnError with Error Boundariesrender-select-memoize - Memoize select functionsrender-select-derived - Use select to derive data and reduce re-rendersrender-notify-props - Use notifyOnChangeProps to limit re-rendersrender-structural-sharing - Understand structural sharingrender-tracked-props - Avoid destructuring all propertiesRead individual reference files for detailed explanations and code examples:
references/{prefix}-{slug}.mdEach reference file contains:
orval skilltest-msw skillreact-19 skillFor the complete guide with all rules expanded: AGENTS.md