AGENT SKILL

tanstack-query

TanStack Query v5 data fetching and caching.

License 许可
MIT
最近更新
2026-11-06
Stars
★ 0
Forks
0

01 前言 Front Matter

name
tanstack-query
license
MIT
metadata
{ "author": "community", "version": "1.0.0" }
description
TanStack Query v5 data fetching and caching.

02 资源文件 41

03 SKILL.md 正文

TanStack Query Best Practices

Comprehensive performance optimization guide for TanStack Query v5 applications. Contains 41 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 or skipToken for conditional queries

3. Mutation Patterns (HIGH)

  • mutation-optimistic-updates - Implement optimistic updates with rollback
  • mutation-invalidate-onsettled - Choose invalidation callbacks by mutation contract
  • 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 - Start follow-up prefetches when keys become known
  • prefetch-server-components - Prefetch in Server Components
  • prefetch-infinite-query - Prefetch infinite lists with queryClient.infiniteQuery (5.102+)
  • 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 - Rely on tracked properties before notifyOnChangeProps
  • render-structural-sharing - Understand structural sharing
  • render-tracked-props - Preserve tracked-property optimization

How to Use

Run in the project root first:

npx -y @pymodel/react-frontend-skills detect                       # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill tanstack-query  # deprecated APIs → rule IDs

Read references/<rule-id>.md for each rule above that matches the task and for each scan hit: why it matters, then incorrect vs. correct code.

Related Skills

  • For mocking API responses in tests, see msw skill
  • For React 19 data fetching patterns, see react skill

04 同仓库更多 Skills

mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

frontend-slides

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

design-dna

Extract, define, and apply design DNA across three dimensions: design system (tokens), design style (qualitative feel), and visual effects (Canvas, WebGL, 3D, particles, shaders, scroll effects, etc.). Use this skill when: (1) a user wants to see the full 3-dimension design structure/schema, (2) a user provides images, screenshots, or URLs of reference designs and wants them analyzed into a structured JSON profile covering all three dimensions, (3) a user has a Design DNA JSON and content and wants a design generated from it, or (4) any combination of these phases. Triggers on "design DNA", "extract design style", "analyze design", "design tokens from reference", "generate design from JSON", "design system from screenshot", "design profile", "style guide JSON", "visual effects analysis", "design with effects", "3d design analysis".

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

wireframe

Generate JSON wireframe with HTML preview

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

social-publishing

Schedule and publish social media posts across 13 platforms (X, LinkedIn, Instagram, Facebook Pages, TikTok, Discord, Telegram, YouTube, Reddit, WordPress, Pinterest) via the SocialClaw API. Use when the user wants to publish, schedule, or manage social media content programmatically. Requires SOCIALCLAW_API_KEY.

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

hermes-tweet

Install and operate Hermes Tweet, a Hermes Agent plugin for X/Twitter research, timeline reading, tweet analysis, and approval-gated private or state-changing operations. Use this skill when installing Hermes Tweet, researching X/Twitter accounts, monitoring launch signals, investigating mentions, auditing giveaways, or preparing gated X operations. Use proactively when a Hermes Agent workflow needs current X/Twitter context. Requires XQUIK_API_KEY for read and action tools.

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

refactoring-ui

Audit and fix visual hierarchy, spacing, color, and depth in web UIs. Use when the user mentions "my UI looks off" (or amateur/unprofessional), "fix the design", "Tailwind styling", "color palette", "visual hierarchy", "design system", "spacing scale", or "component styling". Also trigger when building consistent design tokens, creating dark mode themes, improving data-visualization clarity, or polishing UI details before launch. Covers grayscale-first workflow, constrained design scales, shadows, and component styling. For typeface selection, see web-typography. For usability audits, see ux-heuristics.

★ 0