Agent Skills › simstudioai/sim › react-query-best-practices

react-query-best-practices

GitHub

审计 React Query 使用规范，检查 key 工厂、staleTime、mutation 及服务端状态所有权。支持按范围分析并自动修复或提议更改，确保符合最佳实践。

.agents/skills/react-query-best-practices/SKILL.md simstudioai/sim

Trigger Scenarios

审查 React Query 代码质量检查查询键和缓存配置规范修复服务端状态管理问题

Install

npx skills add simstudioai/sim --skill react-query-best-practices -g -y

More Options

Non-standard path

npx skills add https://github.com/simstudioai/sim/tree/main/.agents/skills/react-query-best-practices -g -y

Use without installing

npx skills use simstudioai/sim@react-query-best-practices

指定 Agent (Claude Code)

npx skills add simstudioai/sim --skill react-query-best-practices -a claude-code -g -y

安装 repo 全部 skill

npx skills add simstudioai/sim --all -g -y

预览 repo 内 skill

npx skills add simstudioai/sim --list

SKILL.md

Frontmatter

{
    "name": "react-query-best-practices",
    "description": "Audit React Query usage for best practices — key factories, staleTime, mutations, and server state ownership",
    "argument-hint": "[scope] [fix=true|false]"
}

React Query Best Practices

Arguments:

scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/hooks/queries/", "whole codebase"
fix: whether to apply fixes (default: true). Set to false to only propose changes.

User arguments: $ARGUMENTS

Context

This codebase uses React Query (TanStack Query) as the single source of truth for all server state. All query hooks live in hooks/queries/. Zustand is used only for client-only UI state. Server data must never be duplicated into useState or Zustand outside of mutation callbacks that coordinate cross-store state.

References

Read these before analyzing:

https://tkdodo.eu/blog/practical-react-query — foundational defaults, custom hooks, avoiding local state copies
https://tkdodo.eu/blog/effective-react-query-keys — key factory pattern, hierarchical keys, fuzzy invalidation
https://tkdodo.eu/blog/react-query-as-a-state-manager — React Query IS your server state manager

Rules to enforce

Query key factories

Every file in hooks/queries/ must have a hierarchical key factory with an all root key
Keys must include intermediate plural keys (lists, details) for prefix invalidation
Key factories are colocated with their query hooks, not in a global keys file

Query hooks

Every queryFn must forward signal for request cancellation
Every query must have an explicit staleTime (default 0 is almost never correct), assigned from a named exported constant — never an inline numeric literal. A server-side prefetch hydrating the same query key must import and reuse that constant instead of restating the number
keepPreviousData / placeholderData only on variable-key queries (where params change), never on static keys
Use enabled to prevent queries from running without required params

Mutations

Use onSettled (not onSuccess) for cache reconciliation — it fires on both success and error
For optimistic updates: save previous data in onMutate, roll back in onError
Use targeted invalidation (entityKeys.lists()) not broad (entityKeys.all) when possible
Don't include mutation objects in useCallback deps — .mutate() is stable

Server state ownership

Never copy query data into useState. Use query data directly in components.
Never copy query data into Zustand stores (exception: mutation callbacks that coordinate cross-store state like temp ID replacement)
The query cache is not a local state manager — setQueryData is for optimistic updates only
Forms are the one deliberate exception: copy server data into local form state with staleTime: Infinity