React Query Best Practices

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)
• 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

Steps

1. Read the references above to understand the guidelines
2. Analyze the specified scope against the rules listed above
3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.