What problem does it solve?
Managing server state in React apps is error-prone: inconsistent query keys, improper caching, incorrect mutation handling, and poor SSR/hydration lead to stale UI, excessive network requests, and subtle bugs. These guidelines consolidate proven patterns to prevent cache collisions, ensure correct invalidation, and keep UI consistent during optimistic updates and offline scenarios.
Core Features & Use Cases
- Query Key Strategy: Always use array keys, include dependencies, enforce serializable key parts, and organize keys hierarchically with factories for large apps.
- Caching & Freshness: Practical staleTime and gcTime recommendations, placeholder vs initial data guidance, and persistence strategies for offline-first apps.
- Mutations & Optimistic Updates: Standardized onMutate/onError/onSettled patterns, rollback context, useMutationState usage, and comprehensive invalidation approaches.
- Advanced Patterns: Prefetching on intent, infinite pagination rules, parallel queries with useQueries, query cancellation with AbortSignal, SSR dehydrate/hydrate patterns, and error boundary integration.
- Use Cases: Dashboards with frequently revisited data, detail pages with pre-seeded SSR data, large lists with infinite scrolling, and offline-capable mobile apps.
Quick Start
Audit your React codebase for useQuery/useMutation patterns and apply the rules to standardize query keys, set appropriate staleTime/gcTime, add optimistic update rollbacks, and implement SSR hydration and persistence where needed.
