tanstack-integration-best-practices

A set of best practices for integrating TanStack Query with TanStack Router and TanStack Start so that data flow, caching coordination, and type safety work consistently across a full-stack application. It is intended to be applied when setting up a new TanStack Start project, wiring TanStack Query into TanStack Router, configuring server-side rendering with query hydration, coordinating caching between router and query, or establishing type-safe data-fetching patterns.

The guidance is organized as prioritized rule categories. Setup rules, marked CRITICAL, cover passing the QueryClient through router context, wrapping correctly with QueryClientProvider, and coordinating staleTime between router and query. SSR integration, also CRITICAL, centers on using setupRouterSsrQueryIntegration for automatic dehydrate and hydrate. HIGH-priority data-flow rules describe using loaders with ensureQueryData, useSuspenseQuery in components, coordinating mutations with query invalidation, and using server functions as query functions. MEDIUM-priority caching rules recommend letting TanStack Query be the single source of truth, coordinating preloading between router and query, and unifying invalidation patterns, while additional SSR rules cover creating a QueryClient per request and handling streaming queries.

Each rule lives in its own file under a rules directory and follows a consistent structure: an explanation of why the pattern matters, a bad example showing the anti-pattern to avoid, a good example showing the recommended implementation, and context on when to apply or skip the rule. A quick-reference list groups the rules by prefix, setup, flow, cache, and ssr, so the relevant guidance can be located by concern, with the SKILL.md acting as an index that points to the detailed rule files.