react-query-best-practices
A comprehensive guide to React Query v4 organized around 24 rules spanning query keys, mutations, caching strategy, WebSocket integration, TypeScript patterns, testing, and common pitfalls. Each rule includes explanations and code examples to help you implement async state management correctly and avoid frequent mistakes.
React Query Best Practices teaches v4 patterns for queries, mutations, caching, and WebSocket integration.
AI-generated summary based on this skill's SKILL.md
Install
arraydude/agent-skills/react-query-best-practices
git clone https://github.com/arraydude/agent-skills
cp -r agent-skills/skills/react-query-best-practices ~/.claude/skills/react-query-best-practicesFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
What are the best practices for react query?
react-query-best-practices covers 24 rules for mastering React Query v4, including query key design, mutation patterns, caching strategies, and error handling. The guide emphasizes proper query invalidation, TypeScript integration, and WebSocket patterns to ensure your async state management is robust and performant.
How do useQuery and useMutation patterns work together?
react-query-best-practices explains how useQuery and useMutation patterns complement each other in React Query v4. It covers synchronizing queries after mutations, implementing optimistic updates, and managing cache invalidation to keep your UI state consistent with server data.
What is the recommended query invalidation strategy in react query?
react-query-best-practices details query invalidation approaches for React Query v4, including exact key matching, prefix-based invalidation, and predicate-based strategies. The guide shows how to invalidate queries after mutations and implement the stale-while-revalidate pattern for optimal performance.
How can I integrate WebSockets with React Query?
react-query-best-practices provides patterns for integrating WebSockets with React Query v4, including real-time subscription management and cache synchronization. The guide covers maintaining query freshness with WebSocket events and avoiding common pitfalls when combining real-time updates with React Query's caching.
What should I know about migrating from React Query v4 to v5?
react-query-best-practices includes guidance on migrating from React Query v4 to v5, covering API changes, new features, and deprecations. The resource helps you understand breaking changes and update your query keys, configuration, and patterns for the latest TanStack Query version.
How do I debug async state issues in React Query?
react-query-best-practices addresses troubleshooting and debugging async state issues in React Query v4, including common mistakes, error handling strategies, and testing approaches. The guide helps you identify stale data problems, cache inconsistencies, and mutation failures through practical examples.
SKILL.md
rendered from the published skill — quoted content, verbatim
React Query Best Practices
> Important: This guide targets React Query v4. Some patterns may differ in v5.
Comprehensive guide for React Query v4 (TanStack Query) based on TkDodo's authoritative blog series. Contains 24 rules across 7 categories, prioritized by impact.
When to Apply
Reference these guidelines when: - Implementing new queries or mutations - Integrating WebSockets with React Query - Setting up query invalidation patterns - Debugging React Query behavior - Optimizing render performance - TypeScript integration questions
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Query Keys & Patterns | CRITICAL | query- |
| 2 | Mutations & Updates | CRITICAL | mutation- |
| 3 | Caching |
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 15 files
skills/react-query-best-practices/AGENTS.md
skills/react-query-best-practices/SKILL.md
skills/react-query-best-practices/rules/cache-refetch-triggers.md
skills/react-query-best-practices/rules/cache-stale-time.md
skills/react-query-best-practices/rules/migration-cache-time-to-gc-time.md
skills/react-query-best-practices/rules/migration-context-to-query-client.md
skills/react-query-best-practices/rules/migration-hydration-boundary.md
skills/react-query-best-practices/rules/migration-initial-page-param.md
skills/react-query-best-practices/rules/migration-keep-previous-data.md
skills/react-query-best-practices/rules/migration-misc-breaking-changes.md
skills/react-query-best-practices/rules/migration-query-callbacks-removed.md
skills/react-query-best-practices/rules/migration-refetch-interval-callback.md
skills/react-query-best-practices/rules/migration-refetch-page-to-max-pages.md
skills/react-query-best-practices/rules/migration-remove-method.md
skills/react-query-best-practices/rules/migration-single-signature.md