router-query

Integrates TanStack Query caching with TanStack Router loaders and SSR hydration.

Updated May 26, 2026
One-click install
npx skills add https://github.com/Albo-Club/albo-os --skill router-query-albo-club
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: router-query
Source: https://github.com/Albo-Club/albo-os/tree/main/.agents/skills/tanstack-router-query
Command: npx skills add https://github.com/Albo-Club/albo-os --skill router-query-albo-club

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @tanstack/react-query, @tanstack/react-router, @tanstack/react-router-ssr-query.

What problem does it solve? Coordinating TanStack Query's cache with TanStack Router's loader system is error-prone: Router's built-in preload cache can serve stale data, module-level QueryClients leak data between SSR requests, and misused prefetching blocks navigation. This Skill provides the correct integration patterns. ## Core Features & Use Cases - Router Context Setup: Inject QueryClient into router context via createRootRouteWithContext, with SSR-safe per-request QueryClient creation. - Loader + Suspense Pattern: Use ensureQueryData in loaders with useSuspenseQuery in components to eliminate loading flashes while keeping cache subscriptions. - SSR Streaming: Configure setupRouterSsrQueryIntegration or manual dehydrate/hydrate for server rendering, plus fire-and-forget prefetchQuery for non-critical data. - Use Case: Building a dashboard route where user data must be ready before render while analytics stream in during SSR without blocking navigation. ## Quick Start Set up TanStack Query with my TanStack Router app so loaders prefetch data and SSR hydration works correctly.

Frequently Asked Questions about router-query

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I use TanStack Query with TanStack Router loaders?▼

Call context.queryClient.ensureQueryData(queryOptions) in the route loader to populate the cache before render, then use useSuspenseQuery with the same queryOptions in the component to subscribe to cached data without a loading flash.

How to set up TanStack Query SSR with TanStack Router?▼

Install @tanstack/react-router-ssr-query and call setupRouterSsrQueryIntegration with your router and queryClient. It handles dehydration, hydration, streaming, and redirects from queries automatically.

Why does TanStack Router serve stale data with React Query?▼

Router's built-in preload cache has a 30-second default staleTime that short-circuits Query's freshness logic. Set defaultPreloadStaleTime: 0 in createRouter so Query controls data freshness.

Can I create QueryClient at module level for SSR?▼

No. A module-level QueryClient singleton is shared across all server requests and leaks user data between them. Create the QueryClient inside the createRouter factory function so each request gets a fresh instance.

Should I await prefetchQuery in a TanStack Router loader?▼

No. Awaiting prefetchQuery blocks the navigation transition and defeats streaming. Fire it without awaiting for non-critical data, or use ensureQueryData when the data must be ready before render.