accelint-tanstack-query-best-practices

100 observers → Immediate refactor: hoist queries to parent component, distribute data via props 51-100 observers → Refactor: hoist queries or use select to subscribe to data subsets <50 observers → Issue is elsewhere, continue to Step 2 Step 2: Check data size and update frequency 1000 items + frequent updates → Disable structural sharing: structuralSharing: false (see fundamentals.md for details) Large payloads (>500KB) → Check network tab, consider pagination or infinite queries Fast updates (<1s interval) → Lower staleTime or use refetchInterval, verify cache strategy Step 3: Check React DevTools Profiler Look for unnecessary re-renders in components using query data Verify select function isn't recreated on every render (use useCallback) Check if derived data should use useMemo instead of inline transformation Profile component render times to identify bottlenecks Network Issues Flaky connections: Configure retry logic: retry: 3, retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000) See query-client-setup.md for production retry configuration Token refresh needed: Implement auth interceptor pattern in queryFn wrapper Use queryClient.setQueryDefaults() for global auth headers See patterns-and-pitfalls.md for token refresh patterns Race conditions: Review invalidation timing: use cancelQueries before setQueryData Check if optimistic updates compete with background refetches Verify mutation onMutate uses await cancelQueries({ queryKey }) Hydration Issues SSR mismatch (hydration error in console): Add suppressHydrationWarning to container element Normalize data: ensure server and client produce identical output (stable timestamps, sorted arrays) Check if user-specific data is being rendered server-side Client-server data drift: Verify revalidateTag timing on server mutations Check if server cache (Next.js use cache) is stale while client cache is fresh Use initialData from server props: initialData: serverData, refetchOnMount: false HydrationBoundary not working: Verify client component boundaries: HydrationBoundary must wrap 'use client' components Check if dehydratedState is being serialized correctly from server Ensure shouldDehydrateQuery includes queries you want to hydrate Freedom Calibration Calibrate guidance specificity to mutation risk: Task Type Freedom Level Guidance Format Example Query configuration High freedom Principles with tables for common patterns "Match staleTime to business requirements" Optimistic updates Medium freedom Complete pattern with rollback handling "Use onMutate/onError/onSettled callbacks" QueryClient setup Low freedom Exact code with critical security warning "NEVER use singleton on server - use factory" The test: "If the agent makes a mistake, what's the consequence?" Server singleton mistake → Data leakage between users (critical security issue) Observer count mistake → Performance degradation (medium impact) staleTime tuning → Suboptimal freshness (low impact) Important Notes Query keys are hashed deterministically - ['tracks', '1'] and ['tracks', 1] create different cache entries Query keys must be JSON-serializable for cache persistence across page reloads and hydration shouldDehydrateQuery with pending status enables streaming without await in server components HydrationBoundary must wrap client components only - server components bypass the boundary revalidateTag vs updateTag matters: revalidateTag uses stale-while-revalidate, updateTag invalidates immediately Background refetches run even when no components are mounted if gcTime hasn't expired Structural sharing runs twice when using select: once on raw data, once on transformed data select only runs on successfully cached data — it is never called in error states; put validation and error throwing in queryFn cancelQueries in onMutate is critical - background refetches can overwrite optimistic updates Context returned from onMutate is passed to onError and onSettled for rollback state