React Query and Zustand patterns for state management. Use when implementing data fetching, caching, mutations, or client-side state. Triggers on tasks involving useQuery, useMutation, Zustand stores, caching, or state management.

State Management with React Query + Zustand Version 1.1.0 TanStack Query v5 Zustand v5 March 2026 Note: This document provides comprehensive patterns for AI agents and LLMs working with TanStack Query v5 and Zustand v5. All examples are verified against v5 APIs. Optimized for automated refactoring, code generation, and state management best practices. v5 Breaking Changes (Quick Reference) TanStack Query v5: cacheTime → gcTime keepPreviousData option → placeholderData: keepPreviousData (imported helper) isPreviousData → isPlaceholderData onSuccess / onError / onSettled removed from useQuery — still valid on useMutation suspense: true on useQuery removed → use useSuspenseQuery Zustand v5: shallow as 2nd arg removed → useShallow from zustand/shallow Selectors returning new references need useShallow to avoid infinite loops Security: Persist Middleware Never persist auth tokens, passwords, or secrets to localStorage/sessionStorage. Use partialize to persist only non sensitive state. Manage tokens via HttpOnly cookies. Comprehensive patterns for server state (React Query) and client state (Zustand). Contains 26+ rules for efficient data fetching and state management. When to Apply Reference these guidelines when: Fetching data from APIs Managing server state and caching Handling mutations and optimistic updates Creating client side stores Combining React Query with Zustand Rule Categories by Priority Priority Category Impact Prefix 1 React Query Basics CRITICAL rq 2 Zustand Store Patterns CRITICAL zs 3 Caching & Invalidation HIGH cache 4 Mutations & Updates HIGH mut 5 Optimistic Updates MEDIUM opt 6 DevTools & Debugging MEDIUM dev 7 Advanced Patterns LOW adv Quick Reference 1. React Query Basics (CRITICAL) rq setup QueryClient and Provider setup rq usequery Basic useQuery patterns rq querykeys Query key organization rq loading error Handle loading and error states rq enabled Conditional queries 2. Zustand Store Patterns (CRITICAL) zs create store Create basic store zs typescript TypeScript store patterns zs selectors Efficient selectors zs actions Action patterns zs persist Persist state to storage 3. Caching & Invalidation (HIGH) cache stale time Configure stale time cache gc time Configure garbage collection cache invalidation Invalidate queries cache prefetch Prefetch data cache initial data Set initial data 4. Mutations & Updates (HIGH) mut usemutation Basic useMutation mut callbacks onSuccess, onError callbacks mut invalidate Invalidate after mutation mut update cache Direct cache updates 5. Optimistic Updates (MEDIUM) opt basic Basic optimistic updates opt rollback Rollback on error opt variables Use mutation variables 6. DevTools & Debugging (MEDIUM) dev react query React Query DevTools dev zustand Zustand DevTools dev debugging Debug strategies 7. Advanced Patterns (LOW) adv infinite queries Infinite scrolling adv parallel queries Parallel requests adv dependent queries Dependent queries adv query zustand Combine RQ with Zustand React Query Patterns Setup Query Keys Factory useQuery Hook useMutation Hook Optimistic Updates Zustand Patterns Basic Store Store with TypeScript and Middleware Selectors for Performance Combining React Query + Zustand How to Use Read individual rule files for detailed explanations and code examples: References React Query (TanStack Query) 1. [TanStack Query Documentation](https://tanstack.com/query/latest) 2. [React Query Overview](https://tanstack.com/query/latest/docs/react/overview) 3. [Queries Guide](https://tanstack.com/query/latest/docs/react/guides/queries) 4. [Mutations Guide](https://tanstack.com/query/latest/docs/react/guides/mutations) 5. [Query Keys Guide](https://tanstack.com/query/latest/docs/react/guides/query keys) 6. [Optimistic Updates](https://tanstack.com/query/latest/docs/react/guides/optimistic updates) 7. [Infinite Queries](https://tanstack.com/query/latest/docs/react/guides/infinite queries) 8. [Paginated Queries](https://tanstack.com/query/latest/docs/react/guides/paginated queries) 9. [React Query DevTools](https://tanstack.com/query/latest/docs/react/devtools) Zustand 1. [Zustand Demo](https://zustand demo.pmnd.rs) 2. [Zustand GitHub](https://github.com/pmndrs/zustand) 3. [Getting Started](https://docs.pmnd.rs/zustand/getting started/introduction) 4. [TypeScript Guide](https://docs.pmnd.rs/zustand/guides/typescript) 5. [Persisting Store Data](https://docs.pmnd.rs/zustand/integrations/persisting store data) 6. [Zustand Recipes](https://github.com/pmndrs/zustand recipes) License This skill is provided as is for educational and development purposes. React Query is MIT licensed by TanStack. Zustand is MIT licensed by Poimandres (pmnd.rs).

state-management