tanstack-integration_skill

Overview

This skill describes practical best practices for integrating TanStack Query with TanStack Router and TanStack Start. It focuses on full-stack data flow, SSR coordination, and unified caching for predictable client and server behavior. The guidance targets setup, loader/component patterns, and per-request SSR concerns to reduce bugs and improve performance.

How this skill works

The skill inspects integration patterns and provides rules that map to concrete implementation steps like provider wrapping, router-context wiring, and query hydration on SSR. It highlights loader-based fetching, useSuspenseQuery usage, mutation invalidation coordination, and a single source of caching governed by TanStack Query. Each rule bundles rationale, anti-patterns, and recommended code patterns for quick application.

When to use it

• Starting a new TanStack Start project that will use TanStack Query and Router
• Integrating client-side routes with server-side rendered data and hydration
• Coordinating cache and preloading behavior between router loaders and query cache
• Implementing type-safe data fetching with server functions and query functions
• Adding streaming or per-request SSR for multi-user server rendering scenarios

Best practices

• Wrap the app with a single QueryClientProvider and pass QueryClient through the router context to ensure consistent cache access
• Use loaders with ensureQueryData to populate the query cache during navigation and avoid duplicate fetches
• Prefer useSuspenseQuery in components for consistent suspense boundaries and to reuse loader-populated data
• Treat TanStack Query as the single source of truth for caching; avoid duplicating cache logic in the router
• Create a fresh QueryClient per SSR request and dehydrate/hydrate using the provided integration helpers
• Coordinate staleTime and preloading strategies between router loaders and query options to prevent unnecessary refetches

Example use cases

• Hydrate server-rendered pages by running loaders that call ensureQueryData, then dehydrate the QueryClient for the client bundle
• Implement optimistic updates: run a mutation, invalidate affected queries, and let the query cache refresh UI state
• Build type-safe route loaders that call server functions for query functions and reuse the same types on client and server
• Configure streaming SSR for long pages: stream HTML while resolving key query data on the server and hydrating progressively on the client
• Set up per-request QueryClient for multi-tenant SSR to avoid cross-request cache leakage