tanstack-integration-best-practices

Integrate TanStack Query with TanStack Router by passing a per-request QueryClient through router context and invoking setupRouterSsrQueryIntegration to automate dehydration, hydration, and streaming SSR. This establishes a single source of truth for data fetching and caching across server renders.

Loading waterfalls occur when router preloading and component-level fetching are uncoordinated. Fix this by configuring the router with defaultPreloadStaleTime set to 0 and using loaders that call ensureQueryData to hydrate the Query cache before components render with useSuspenseQuery.

Yes, a per-request QueryClient is required for TanStack Start SSR. Passing it through the router context enables SSR-safe caching, prevents conflicting caches across requests, and provides type-safe access to the cache within loaders and hooks.

Handle mutation invalidation by coordinating optimistic updates, background refetches, and cross-route cache sharing through the shared per-request QueryClient. This ensures consistent cache behavior and predictable data flow across navigation-driven loaders and components.

Prevent broken SSR hydration by using setupRouterSsrQueryIntegration to automate dehydration and hydration. Combine this with navigation-driven loaders calling ensureQueryData so the server and client share a single, predictable data flow without cache conflicts.

Yes, TanStack Router supports useSuspenseQuery without loading waterfalls when loaders use ensureQueryData to preload data into the Query cache. Components can then rely on the preloaded cache, preventing sequential fetches during navigation and rendering.