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→gcTimekeepPreviousDataoption →placeholderData: keepPreviousData(imported helper)isPreviousData→isPlaceholderDataonSuccess/onError/onSettledremoved fromuseQuery— still valid onuseMutationsuspense: trueonuseQueryremoved → useuseSuspenseQuery
Zustand v5:
shallowas 2nd arg removed →useShallowfromzustand/shallow- Selectors returning new references need
useShallowto avoid infinite loops
Security: Persist Middleware
Never persist auth tokens, passwords, or secrets to localStorage/sessionStorage. Use
partializeto 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
Quick Reference
1. React Query Basics (CRITICAL)
rq-setup- QueryClient and Provider setuprq-usequery- Basic useQuery patternsrq-querykeys- Query key organizationrq-loading-error- Handle loading and error statesrq-enabled- Conditional queries
2. Zustand Store Patterns (CRITICAL)
zs-create-store- Create basic storezs-typescript- TypeScript store patternszs-selectors- Efficient selectorszs-actions- Action patternszs-persist- Persist state to storage
3. Caching & Invalidation (HIGH)
cache-stale-time- Configure stale timecache-gc-time- Configure garbage collectioncache-invalidation- Invalidate queriescache-prefetch- Prefetch datacache-initial-data- Set initial data
4. Mutations & Updates (HIGH)
mut-usemutation- Basic useMutationmut-callbacks- onSuccess, onError callbacksmut-invalidate- Invalidate after mutationmut-update-cache- Direct cache updates
5. Optimistic Updates (MEDIUM)
opt-basic- Basic optimistic updatesopt-rollback- Rollback on erroropt-variables- Use mutation variables
6. DevTools & Debugging (MEDIUM)
dev-react-query- React Query DevToolsdev-zustand- Zustand DevToolsdev-debugging- Debug strategies
7. Advanced Patterns (LOW)
adv-infinite-queries- Infinite scrollingadv-parallel-queries- Parallel requestsadv-dependent-queries- Dependent queriesadv-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)
- TanStack Query Documentation
- React Query Overview
- Queries Guide
- Mutations Guide
- Query Keys Guide
- Optimistic Updates
- Infinite Queries
- Paginated Queries
- React Query DevTools
Zustand
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).


