react-query-best-practices

Audit React Query code for hierarchical keys, staleTime, and server state ownership.

Updated Apr 16, 2026

Search Tags:#frontend #best-practices #state-management #react-query #tanstack-query #query-keys

Ready to run

npx skills add https://github.com/tunacosgun/sim --skill react-query-best-practices

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: react-query-best-practices
Source: https://github.com/tunacosgun/sim/tree/main/.agents/skills/react-query-best-practices
Command: npx skills add https://github.com/tunacosgun/sim --skill react-query-best-practices

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Inconsistent React Query usage leads to stale data, brittle server-state handling, and fragile cache management across a codebase.

Core Features & Use Cases

Enforce hierarchical query keys with an all root key to support reliable invalidation.
Ensure explicit staleTime on all queries and proper use of onSettled for mutations.
Keep query hooks colocated with their keys (hooks/queries) and avoid duplicating server data in local state.

Quick Start

Audit the codebase to identify and fix violations of React Query best practices.

Frequently Asked Questions about react-query-best-practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I enforce React Query best practices for query keys and staleTime across my codebase?▼

React Query best practices are enforced by auditing hooks to ensure hierarchical query keys with an all root key, explicit non-zero staleTime on queries, and proper server state ownership to prevent stale data and fragile cache management.

What is the best way to structure TanStack Query keys for reliable cache invalidation?▼

The best way to structure TanStack Query keys is using hierarchical key factories that include an all root key, ensuring reliable invalidation and consistent server state management across colocated query hooks.

How do I prevent stale data and duplicate server state in React Query hooks?▼

Prevent stale data and duplicate server state by avoiding local state duplication, specifying explicit non-zero staleTime on queries, and using onSettled in mutations for targeted cache reconciliation and invalidation.

Why should React Query mutations use onSettled for cache invalidation?▼

React Query mutations should use onSettled for cache invalidation to ensure proper cache reconciliation, triggering targeted invalidation reliably after mutation completion to maintain consistent server state.

Can I configure the scope of a React Query audit to target specific directories?▼

Yes, you can configure the audit scope by providing a scope argument, targeting specific directories like hooks/queries and related mutation patterns to enforce React Query best practices where needed.

Do I need to forward the signal in queryFn for React Query cancellation to work properly?▼

Yes, each queryFn must forward the signal for cancellation to work properly, ensuring requests abort correctly when queries become inactive or stale, maintaining robust server state handling.