code-enforce-route-data

Prevent SSR hydration drift in TanStack Start by aligning server-side loader prefetch with React Query reads using colocated queryOptions and ensureQueryData, ensuring the server and client share an identical data source to avoid mismatches.

Prefetch the React Query cache in a TanStack Start route loader by calling queryClient.ensureQueryData with your colocated queryOptions. Use Promise.all to pre-warm multiple queries simultaneously so the first paint has data without loading flashes.

TanStack Start components show different data than the server loader when the prefetch and read patterns diverge, causing cache drift. Enforce a single source of truth by importing colocated queryOptions and hooks from src/queries in both the loader and the component.

Prefetch route data when queries depend on URL search params by wiring loaderDeps and validateSearch in your TanStack Start route. This passes validated search parameters to your loader, allowing ensureQueryData to prefetch the correct colocated queryOptions.

You cannot use useLoaderData to read server data when enforcing this TanStack Start pattern. You must read data through React Query hooks using colocated queryOptions, while the loader strictly uses ensureQueryData to warm the cache and avoid hydration mismatches.

Warm route data cache before navigation by using the @tanstack/react-router Link component for intent prefetching. This warms the loader cache before the user clicks, aligning navigation behavior with data requirements to eliminate loading flashes.