deckardger/tanstack-agent-skills
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
FAQ
No. Let TanStack Query manage caching; coordinate the router to populate or preload the query cache rather than duplicating state.
How do I avoid duplicate fetches between loaders and components?
Use loaders to call ensureQueryData and have components useSuspenseQuery or standard query hooks so they read from the populated cache instead of refetching.
4 skills
This skill helps you implement best practices for integrating TanStack Query, Router, and Start across SSR, caching, and data flow.
This skill helps you implement TanStack Query best practices for data fetching, caching, mutations, and SSR in React applications.
This skill helps you apply TanStack Router best practices for type-safe routing, data loading, and navigation in complex React apps.
This skill helps you implement TanStack Start best practices for full-stack React apps, improving security, SSR reliability, and deployment efficiency.
