TanStack Query v5 Server State & Cache Factory

--- description: TanStack Query v5 Server State & Cache Factory - Best practices for TanStack Query v5: queryKey factories for bulletproof cache invalidation, mutation optimistic updates, and elimination of useEffect data fetching. globs: src/queries/**/*.{ts,tsx}, src/hooks/**/*.{ts,tsx} alwaysApply: false author: "Tanner Linsley & TanStack Team (@tannerlinsley)" contributor_url: "https://github.com/tannerlinsley" verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tanstack-query-v5" --- # TanStack Query v5 Server State & Cache Factory > **Severity**: HIGH | **Category**: frontend > **Anti-Pattern Warning**: AI uses inline strings for query keys, causing impossible cache invalidations or N+1 fetch waterfalls. ## System Constraints You are a data synchronization expert using TanStack Query v5. Query keys must be structured as tuples generated by a centralized Query Key Factory. Always handle error and pending states gracefully. ## Strict Guidelines - Use query key factory objects to centralize and namespace query keys. - In TanStack Query v5, use the object signature: useQuery({ queryKey, queryFn }). - Perform optimistic updates with onMutate, onError rollback, and onSettled invalidation. ## Bad vs Good Implementations ### Query Key Factory Pattern #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Ad-hoc string keys easily cause typos and fail to invalidate sub-resources reliably. ```typescript // Anti-pattern: Ad-hoc query keys scattered across files useQuery({ queryKey: ["users", userId], // Invalidation will be error-prone across 10 files queryFn: () => fetchUser(userId) }); ``` #### Production Standard (Correct) > **Standard**: Centralized query key factory provides type-safe invalidation of single users or all user lists. ```typescript // Standard: Centralized Query Key Factory export const userKeys = { all: ["users"] as const, lists: () => [...userKeys.all, "list"] as const, detail: (id: string) => [...userKeys.all, "detail", id] as const, }; export function useUser(id: string) { return useQuery({ queryKey: userKeys.detail(id), queryFn: () => fetchUser(id), staleTime: 1000 * 60 * 5, // 5 minutes }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TanStack Query v5 Server State & Cache Factory

TanStack Query v5 Server State & Cache Factory defines an industrial-grade behavioral standard for frontend engineering. Best practices for TanStack Query v5: queryKey factories for bulletproof cache invalidation, mutation optimistic updates, and elimination of useEffect data fetching. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: AI uses inline strings for query keys, causing impossible cache invalidations or N+1 fetch waterfalls. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	AI uses inline strings for query keys, causing impossible cache invalidations or N+1 fetch waterfalls.	High	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Use query key factory objects to centralize and namespace query keys.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

In TanStack Query v5, use the object signature

In TanStack Query v5, use the object signature: useQuery({ queryKey, queryFn }).

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Perform optimistic updates with onMutate, onError rollback, and onSettled invalidation.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is TanStack Query v5 Server State & Cache Factory critical for AI coding assistants?

Best practices for TanStack Query v5: queryKey factories for bulletproof cache invalidation, mutation optimistic updates, and elimination of useEffect data fetching. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (AI uses inline strings for query keys, causing impossible cache invalidations or N+1 fetch waterfalls.) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.