tanstack-query

Files (45)

• AGENTS.md
• README.md
• SKILL.md
• metadata.json
• _sections.md · references/
• cache-enabled-option.md · references/
• cache-global-defaults.md · references/
• cache-invalidation-precision.md · references/
• cache-placeholder-vs-initial.md · references/
• cache-refetch-triggers.md · references/
• cache-staletime-gctime.md · references/
• error-conditional-retry.md · references/
• error-display-patterns.md · references/
• error-global-handler.md · references/
• error-retry-config.md · references/
• error-throw-on-error.md · references/
• infinite-flatten-pages.md · references/
• infinite-loading-states.md · references/
• infinite-max-pages.md · references/
• infinite-refetch-behavior.md · references/
• mutation-avoid-parallel.md · references/
• mutation-cancel-queries.md · references/
• mutation-invalidate-onsettled.md · references/
• mutation-optimistic-updates.md · references/
• mutation-setquerydata.md · references/
• prefetch-avoid-waterfalls.md · references/
• prefetch-flatten-api.md · references/
• prefetch-in-queryfn.md · references/
• prefetch-on-hover.md · references/
• prefetch-server-components.md · references/
• render-notify-props.md · references/
• render-select-derived.md · references/
• render-select-memoize.md · references/
• render-structural-sharing.md · references/
• render-tracked-props.md · references/
• suspense-boundaries-placement.md · references/
• suspense-error-boundaries.md · references/
• suspense-parallel-queries.md · references/
• suspense-use-suspense-hooks.md · references/
• tquery-always-arrays.md · references/
• tquery-colocate-keys.md · references/
• tquery-hierarchical-keys.md · references/
• tquery-key-factories.md · references/
• tquery-options-pattern.md · references/
• tquery-serializable-objects.md · references/

SKILL.md (first lines)

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

From pproenca/dot-skills, MIT.

More from pproenca/dot-skills