playbooks

home / skills / pproenca / dot-skills / tanstack-query

tanstack-query skill

/skills/.curated/tanstack-query

This skill helps optimize TanStack Query v5 performance by guiding query key design, caching, mutations, prefetching, and render strategies.

npx playbooks add skill pproenca/dot-skills --skill tanstack-query

Review the files below or copy the command above to add this skill to your agents.

Files (45)
SKILL.md
5.2 KB
---
name: tanstack-query
description: 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).
license: MIT
metadata:
  author: community
  version: "1.0.0"
---

# TanStack Query Best Practices

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.

## When to Apply

Reference these guidelines when:
- Writing new queries, mutations, or data fetching logic
- Implementing caching strategies (staleTime, gcTime)
- Reviewing code for performance issues or request waterfalls
- Refactoring existing TanStack Query code
- Implementing infinite queries, Suspense, or optimistic updates

## Rule Categories by Priority

| 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-` |

## Quick Reference

### 1. Query Key Structure (CRITICAL)

- `tquery-key-factories` - Use centralized query key factories
- `tquery-hierarchical-keys` - Structure keys from generic to specific
- `tquery-always-arrays` - Always use array query keys
- `tquery-serializable-objects` - Use serializable objects in keys
- `tquery-options-pattern` - Use queryOptions for type-safe sharing
- `tquery-colocate-keys` - Colocate query keys with features

### 2. Caching Configuration (CRITICAL)

- `cache-staletime-gctime` - Understand staleTime vs gcTime
- `cache-global-defaults` - Configure global defaults appropriately
- `cache-placeholder-vs-initial` - Use placeholderData vs initialData correctly
- `cache-invalidation-precision` - Invalidate with precision
- `cache-refetch-triggers` - Control automatic refetch triggers
- `cache-enabled-option` - Use enabled for conditional queries

### 3. Mutation Patterns (HIGH)

- `mutation-optimistic-updates` - Implement optimistic updates with rollback
- `mutation-invalidate-onsettled` - Invalidate in onSettled, not onSuccess
- `mutation-cancel-queries` - Cancel queries before optimistic updates
- `mutation-setquerydata` - Use setQueryData for immediate cache updates
- `mutation-avoid-parallel` - Avoid parallel mutations on same data

### 4. Prefetching & Waterfalls (HIGH)

- `prefetch-avoid-waterfalls` - Avoid request waterfalls
- `prefetch-on-hover` - Prefetch on hover for perceived speed
- `prefetch-in-queryfn` - Prefetch dependent data in queryFn
- `prefetch-server-components` - Prefetch in Server Components
- `prefetch-flatten-api` - Flatten API to reduce waterfalls

### 5. Infinite Queries (MEDIUM)

- `infinite-max-pages` - Limit infinite query pages with maxPages
- `infinite-flatten-pages` - Flatten pages for rendering
- `infinite-refetch-behavior` - Understand infinite query refetch behavior
- `infinite-loading-states` - Handle infinite query loading states correctly

### 6. Suspense Integration (MEDIUM)

- `suspense-use-suspense-hooks` - Use Suspense hooks for simpler loading states
- `suspense-error-boundaries` - Always pair Suspense with Error Boundaries
- `suspense-parallel-queries` - Combine Suspense queries with useSuspenseQueries
- `suspense-boundaries-placement` - Place Suspense boundaries strategically

### 7. Error & Retry Handling (MEDIUM)

- `error-retry-config` - Configure retry with exponential backoff
- `error-conditional-retry` - Use conditional retry based on error type
- `error-global-handler` - Use global error handler for common errors
- `error-display-patterns` - Display errors appropriately
- `error-throw-on-error` - Use throwOnError with Error Boundaries

### 8. Render Optimization (LOW-MEDIUM)

- `render-select-memoize` - Memoize select functions
- `render-select-derived` - Use select to derive data and reduce re-renders
- `render-notify-props` - Use notifyOnChangeProps to limit re-renders
- `render-structural-sharing` - Understand structural sharing
- `render-tracked-props` - Avoid destructuring all properties

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- Reference files: `references/{prefix}-{slug}.md`

Each reference file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references

## Related Skills

- For generating type-safe query hooks, see `orval` skill
- For mocking API responses in tests, see `test-msw` skill
- For React 19 data fetching patterns, see `react-19` skill

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

Overview

This skill provides a prioritized, practical guide to performance optimization with TanStack Query v5, focused on data fetching, caching, mutations, and query patterns. It distills 40 concrete rules across eight categories to guide refactors, new implementations, and automated code transformations. Use it to reduce request waterfalls, improve cache hit rates, and stabilize UI rendering.

How this skill works

The skill inspects query and mutation usage patterns (useQuery, useMutation), queryClient interactions, prefetch flows, and caching configuration such as staleTime and gcTime. It recommends structural changes like centralized key factories, precise invalidation, optimistic mutation patterns, and Suspense integration. It maps each recommendation to a priority level so you can apply the highest-impact changes first.

When to use it

  • When adding or refactoring useQuery/useMutation logic
  • When defining caching policies (staleTime, gcTime, placeholderData)
  • During code reviews that surface request waterfalls or redundant refetches
  • When implementing prefetching, infinite queries, or optimistic updates
  • When optimizing render performance related to cached data

Best practices

  • Centralize query key factories and always use array keys to ensure consistency and serializability
  • Set global defaults and use staleTime/gcTime intentionally to avoid excessive refetching or premature cache eviction
  • Implement optimistic updates with rollback and cancel queries before applying optimistic data
  • Avoid request waterfalls by prefetching dependent data or flattening API endpoints
  • Use select, memoization, and notifyOnChangeProps to reduce re-renders and enable structural sharing

Example use cases

  • Refactor a team codebase to replace ad-hoc keys with hierarchical, centralized key factories
  • Tune caching for a dashboard to reduce network traffic by increasing staleTime and using placeholderData
  • Add optimistic updates to mutations that update list items and rollback on error
  • Prefetch item details on hover to improve perceived navigation speed and avoid waterfalls
  • Convert parallel dependent queries to prefetch in server components to speed initial render

FAQ

Does this skill generate type-safe query hooks from OpenAPI?

No. Use a dedicated tool for generating query hooks from OpenAPI, such as the orval skill.

Does this cover mocking API responses in tests?

No. For test mocking use a test mocking skill such as test-msw; this skill focuses on runtime fetch, cache, and mutation patterns.