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
Decision gist · record as of 2026-07-21
React Query Best Practices teaches v4 patterns for queries, mutations, caching, and WebSocket integration. 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.
Use it when
- react-query-best-practices explains how useQuery and useMutation patterns complement each other in React Query v4.
- react-query-best-practices details query invalidation approaches for React Query v4, including exact key matching.
Verify before relying
Read SKILL.md below before installing (40 files). Open directory: indexed for reading, not audited.
Install
arraydude/agent-skills/react-query-best-practices
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently 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)
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
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Learn React Query v4 best practices and patterns”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
TanStack Query v5 handles server state management in React through data fetching, caching, and mutation patterns. Learn QueryClient setup, hook usage with the v5 object syntax, and common migration issues from v4.
TanStack Query provides asynchronous state management for server data across React, Vue, Solid, Svelte, and Angular. It handles caching, background synchronization, pagination, infinite scrolling, and optimistic updates automatically. Use queries for data fetching and mutations for server modifications, with lifecycle hooks for managing side effects and rollback scenarios.
TanStack Query handles server-state fetching and caching in React applications, automating data synchronization and eliminating manual boilerplate. It provides built-in background refetching, optimistic mutations, intelligent cache invalidation, and pagination support for complex data workflows.
Master server state management and data fetching with TanStack Query through expert guidelines covering query organization, mutations, caching strategies, and performance optimization. This skill teaches you how to structure queries with factory patterns, implement optimistic updates, handle errors gracefully, and prefetch data efficiently.
TanStack Query is an async state manager that handles server data fetching, caching, and synchronization in React applications. It automates cache invalidation, deduplication, background updates, and stale data management—you supply a queryFn that returns a Promise, and the library handles the rest. Use it for infinite scrolling, offline-first apps, complex cache strategies, and hybrid server/client architectures.
This skill covers expert patterns for TanStack Query in modern React with Next.js App Router, including QueryClient configuration, query key factories, cache invalidation, and optimistic updates. Learn critical anti-patterns to avoid—like singleton QueryClients on servers, unstable query keys, and N observers per list item—plus decision matrices for cache configuration and mutation strategies.