# Tanstack React Query Best Practices

> TanStack Query conventions for cache-backed React server state. Use when creating or reviewing React queries, mutations, query keys, or cache updates.

- Skill: `bastidood/tanstack-react-query-best-practices` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add bastidood/tanstack-react-query-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bastidood/tanstack-react-query-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: BastiDood (https://skillmd.com/u/bastidood)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bastidood/tanstack-react-query-best-practices

---


# TanStack React Query Best Practices

Treat server data as cache-backed asynchronous state with an explicit owner, identity, and view boundary; the outcome is reliable loading and error handling plus focused updates after writes.

## Library Sources

- GitHub repository ID: `TanStack/query`
- Context7 library ID: `/tanstack/query`
- DeepWiki repository ID: `TanStack/query`

Use Context7 for current documentation and DeepWiki for implementation details.

## References

Read the references that apply to the current task before writing or reviewing TanStack Query code.

1. Let TanStack Query own server-request lifecycle and cache identity.
   - [Let TanStack Query own request lifecycle](./references/request-ownership.md) rather than duplicating it with effects and local state.
   - [Put every response-changing request input in cache identity](./references/cache-identity.md) so distinct results never reuse one entry.
   - [Read request inputs exclusively from the query function's context argument](./references/query-function-inputs.md), never from captured request variables.
   - [Preserve absent identifiers and disable the request](./references/absent-identifiers.md) instead of fabricating a record key.
   - [Partition visibility-sensitive cached data by actor identity](./references/actor-identity-and-secrets.md) without exposing credentials in keys.
2. Resolve query status before presentation consumes data.
   - [Resolve query status at a Loader and Inner boundary](./references/loader-and-inner.md), keeping presentation free of optional data and transport state.
   - [Publish query identity through loader prop contracts](./references/loader-prop-contracts.md) while resolved components receive non-null data.
   - [Destructure only consumed query fields](./references/result-destructuring.md) so dependencies and props express semantic needs.
3. Keep mutation data, callbacks, and cache updates scoped to each operation.
   - [Consume named mutation result fields](./references/mutation-result-destructuring.md) because the complete `useMutation` result is not referentially stable.
   - [Pass changing operation input through mutation variables](./references/mutation-variables.md), not a mutation hook's construction closure.
   - [Parse user-controlled values before mutation invocation](./references/mutation-form-integration.md).
   - [Separate mutation callback lifecycles](./references/mutation-callback-lifecycle.md) by putting every-invocation policy in the definition and mounted UI consequences at the call site instead of aggregate-status effects.
   - [Invalidate the narrow stale entry identified by successful variables](./references/mutation-invalidation.md).