tanstack-query-best-practices
TanStack Query (React Query) best practices for data fetching, caching, mutations, and server state management. Activate when building data-driven React applications with server state.
- License 许可
- MIT
- 最近更新
- 2026-03-27
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- tanstack-query-best-practices
- description
- TanStack Query (React Query) best practices for data fetching, caching, mutations, and server state management. Activate when building data-driven React applications with server state.
02 资源文件 23
- 参考文档rules/cache-gc-time.md2.8 KB
- 参考文档rules/cache-invalidation.md3.6 KB
- 参考文档rules/cache-placeholder-vs-initial.md4.6 KB
- 参考文档rules/cache-stale-time.md2.5 KB
- 参考文档rules/err-error-boundaries.md3.6 KB
- 参考文档rules/inf-page-params.md3.5 KB
- 参考文档rules/mut-invalidate-queries.md3.7 KB
- 参考文档rules/mut-mutation-state.md4.1 KB
- 参考文档rules/mut-optimistic-updates.md3.9 KB
- 参考文档rules/network-mode.md4.5 KB
- 参考文档rules/parallel-use-queries.md3.8 KB
- 参考文档rules/perf-select-transform.md3.7 KB
- 参考文档rules/persist-queries.md4.8 KB
- 参考文档rules/pf-intent-prefetch.md3.3 KB
- 参考文档rules/qk-array-structure.md1.3 KB
- 参考文档rules/qk-factory-pattern.md3.0 KB
- 参考文档rules/qk-hierarchical-organization.md2.1 KB
- 参考文档rules/qk-include-dependencies.md1.8 KB
- 参考文档rules/qk-serializable.md2.5 KB
- 参考文档rules/query-cancellation.md4.5 KB
- 参考文档rules/ssr-dehydration.md3.8 KB
- 脚本scripts/estimate.test.ts1.9 KB
- 脚本scripts/estimate.ts4.9 KB
03 SKILL.md 正文
TanStack Query Best Practices
Comprehensive guidelines for implementing TanStack Query (React Query) patterns in React applications. These rules optimize data fetching, caching, mutations, and server state synchronization.
When to Apply
- Creating new data fetching logic
- Setting up query configurations
- Implementing mutations and optimistic updates
- Configuring caching strategies
- Integrating with SSR/SSG
- Refactoring existing data fetching code
Rule Categories by Priority
| Priority | Category | Rules | Impact |
|---|---|---|---|
| CRITICAL | Query Keys | 5 rules | Prevents cache bugs and data inconsistencies |
| CRITICAL | Caching | 5 rules | Optimizes performance and data freshness |
| HIGH | Mutations | 6 rules | Ensures data integrity and UI consistency |
| HIGH | Error Handling | 3 rules | Prevents poor user experiences |
| MEDIUM | Prefetching | 4 rules | Improves perceived performance |
| MEDIUM | Parallel Queries | 2 rules | Enables dynamic parallel fetching |
| MEDIUM | Infinite Queries | 3 rules | Prevents pagination bugs |
| MEDIUM | SSR Integration | 4 rules | Enables proper hydration |
| LOW | Performance | 4 rules | Reduces unnecessary re-renders |
| LOW | Offline Support | 2 rules | Enables offline-first patterns |
Quick Reference
Query Keys (Prefix: qk-)
qk-array-structure— Always use arrays for query keysqk-include-dependencies— Include all variables the query depends onqk-hierarchical-organization— Organize keys hierarchically (entity → id → filters)qk-factory-pattern— Use query key factories for complex applicationsqk-serializable— Ensure all key parts are JSON-serializable
Caching (Prefix: cache-)
cache-stale-time— Set appropriate staleTime based on data volatilitycache-gc-time— Configure gcTime for inactive query retentioncache-defaults— Set sensible defaults at QueryClient levelcache-invalidation— Use targeted invalidation over broad patternscache-placeholder-vs-initial— Understand placeholder vs initial data differences
Mutations (Prefix: mut-)
mut-invalidate-queries— Always invalidate related queries after mutationsmut-optimistic-updates— Implement optimistic updates for responsive UImut-rollback-context— Provide rollback context from onMutatemut-error-handling— Handle mutation errors gracefullymut-loading-states— Use isPending for mutation loading statesmut-mutation-state— Use useMutationState for cross-component tracking
Error Handling (Prefix: err-)
err-error-boundaries— Use error boundaries with useQueryErrorResetBoundaryerr-retry-config— Configure retry logic appropriatelyerr-fallback-data— Provide fallback data when appropriate
Prefetching (Prefix: pf-)
pf-intent-prefetch— Prefetch on user intent (hover, focus)pf-route-prefetch— Prefetch data during route transitionspf-stale-time-config— Set staleTime when prefetchingpf-ensure-query-data— Use ensureQueryData for conditional prefetching
Infinite Queries (Prefix: inf-)
inf-page-params— Always provide getNextPageParaminf-loading-guards— Check isFetchingNextPage before fetching moreinf-max-pages— Consider maxPages for large datasets
SSR Integration (Prefix: ssr-)
ssr-dehydration— Use dehydrate/hydrate pattern for SSRssr-client-per-request— Create QueryClient per requestssr-stale-time-server— Set higher staleTime on serverssr-hydration-boundary— Wrap with HydrationBoundary
Parallel Queries (Prefix: parallel-)
parallel-use-queries— Use useQueries for dynamic parallel queriesquery-cancellation— Implement query cancellation properly
Performance (Prefix: perf-)
perf-select-transform— Use select to transform/filter dataperf-structural-sharing— Leverage structural sharingperf-notify-change-props— Limit re-renders with notifyOnChangePropsperf-placeholder-data— Use placeholderData for instant UI
Offline Support (Prefix: offline-)
network-mode— Configure network mode for offline supportpersist-queries— Configure query persistence for offline support
How to Use
Each rule file in the rules/ directory contains:
- Explanation — Why this pattern matters
- Bad Example — Anti-pattern to avoid
- Good Example — Recommended implementation
- Context — When to apply or skip this rule
Full Reference
See individual rule files in rules/ directory for detailed guidance and code examples.
04 同仓库更多 Skills
zustand
Zustand state management guide. Use when working with store code (src/store/**), implementing actions, managing state, or creating slices. Triggers on Zustand store development, state management questions, or action implementation.
web-vitals
暂无简介
vercel-storage
Vercel storage expert guidance — Blob, Edge Config, and Marketplace storage (Neon Postgres, Upstash Redis). Use when choosing, configuring, or using data storage with Vercel applications.
vercel-functions
Vercel Functions expert guidance — Serverless Functions, Edge Functions, Fluid Compute, streaming, Cron Jobs, and runtime configuration. Use when configuring, debugging, or optimizing server-side code running on Vercel.
ui-ux-pro-max
UI/UX design intelligence for web and mobile. Includes 50+ styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, and 25 chart types across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, and HTML/CSS). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, and check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, and mobile app. Elements: button, modal, navbar, sidebar, card, table, form, and chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, and flat design. Topics: color systems, accessibility, animation, layout, typography, font pairing, spacing, interaction states, shadow, and gradient. Integrations: shadcn/ui MCP for component search and examples.
turborepo
Turborepo monorepo build system guidance. Triggers on: turbo.json, task pipelines, dependsOn, caching, remote cache, the "turbo" CLI, --filter, --affected, CI optimization, environment variables, internal packages, monorepo structure/best practices, and boundaries. Use when user: configures tasks/workflows/pipelines, creates packages, sets up monorepo, shares code between apps, runs changed/affected packages, debugs cache, or has apps/packages directories.