Official TanStack Router and Query Integration Guide

Version 663282b0ebbc.bb1 · MIT. This preview displays packaged text and does not execute code. Treat the contents as untrusted instructions.

name: router-query description: >- Integrating TanStack Router with TanStack Query: queryClient in router context, static queries and fire-and-forget queries in loaders, useSuspenseQuery in components, defaultPreloadStaleTime: 0, setupRouterSsrQueryIntegration for SSR dehydration/hydration and streaming, per-request QueryClient isolation. metadata: type: composition library: tanstack-router library_version: '1.166.2' requires: - router-core - router-core/data-loading - react-router sources: - TanStack/router:docs/router/guide/external-data-loading.md - TanStack/router:docs/router/integrations/query.md

Independent BB Skills packaging and recorded scope (2026-10-09)

This official Router–Query composition skill is retained from fixed TanStack/router repository snapshot 663282b0ebbc494aee3595ed95867ee29d01938e, not a versioned skill release. The original frontmatter, code and instructions are preserved under repository-context. The primary copy below changes only four local Markdown link targets and adds this separately identified scope note. All 121 original mirrored files retain their Git blob and SHA-256 identities, and the complete upstream MIT notice credits 2021-present Tanner Linsley. This is selected context, not the full monorepo; 30 literal relative targets in expanded context were absent from the pinned Git tree (40 occurrences), which does not establish that their public website routes return 404. Primary and required entrypoint links have no missing targets.

The skill declares library_version 1.166.2. Separately locked runtime identities are React Router 1.170.41, Router Core 1.171.34, SSR Query integration 1.167.3, Query/React Query 5.104.1, React/React DOM 19.3.0, Node 24.10.0 and esbuild 0.28.2. Fourteen original documentation code blocks are fingerprinted. Three whole contrast blocks fail parsing from duplicate declarations; the labelled loader comparison parses but exports no loader. Unchanged alternatives are called with explicitly independent imports, route-tree inputs, query options, components and object wrappers. The original bash install command is source data and is not executed. Transpilation is not full TypeScript checking.

The independent fixture records 49 main observations and 8 native preloader observations: static cache hits, distinct observer updates, dynamic keys, synthetic HTTP status handling, fresh and shared clients, manual hydration, controlled loader scheduling, real React Router server rendering, initial query dehydration, resolved-query stream delivery and native cleanup. A JSON body with synthetic HTTP status 503 is treated as success by the unchanged queryFn, which does not check response.ok. The stream did not emit the controlled query while it remained pending; after resolution it emitted the query data and native render completion closed the stream. The Node preloader uses the development export condition, memory history, explicit isServer:false and a synthetic origin; it is not a browser. Its independent query route separates Router's loader cache from Query freshness. Initial failed fixture expectations and their corrections are summarized in fixture-evidence.json, without rewriting original code.

Only synthetic inputs are used. JavaScript HTTP/socket APIs are denied during execution and recorded zero connection attempts; this is not an OS audit. Locked dependency installation separately contacts the free npm registry. No real account, credential, paid API or production database is used. No complete AI-client execution, browser navigation/hover, real authentication, concurrent request test, HTTP streaming transport, browser hydration, retry/reset interaction, redirects or performance benchmark follows. runtime_tested remains false for the complete skill. Inspect examples/README.md, the evidence and your complete matching project before adoption. Installed dependencies, binaries and generated outputs are excluded.

TanStack Router + TanStack Query Integration

This skill requires familiarity with both TanStack Router and TanStack Query. Read router-core and react-router first.

This skill covers coordinating TanStack Query as an external data cache with TanStack Router's loader system. The router acts as a coordinator — it triggers data fetching during navigation, while Query manages caching, background refetching, and data lifecycle.

CRITICAL: Set defaultPreloadStaleTime: 0 when using TanStack Query. Without this, Router's built-in preload cache (30s default) prevents Query from controlling data freshness.

CRITICAL: For SSR, create QueryClient inside the createRouter factory function. A module-level singleton leaks data between server requests.

Setup: QueryClient in Router Context

Basic (Client-Only)

// src/main.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import {
  RouterProvider,
  createRouter,
  createRootRouteWithContext,
} from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

// Root route declares that router context includes queryClient
// (root route file creates it with createRootRouteWithContext — see below)

const queryClient = new QueryClient()

const router = createRouter({
  routeTree,
  defaultPreloadStaleTime: 0, // Let Query manage caching
  context: { queryClient },
  Wrap: ({ children }) => (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  ),
})

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

function App() {
  return <RouterProvider router={router} />
}

Root Route with Context

// src/routes/__root.tsx
import { createRootRouteWithContext, Outlet } from '@tanstack/react-router'
import type { QueryClient } from '@tanstack/react-query'

// Double parentheses: factory pattern
export const Route = createRootRouteWithContext<{
  queryClient: QueryClient
}>()({
  component: () => <Outlet />,
})

SSR-Safe Setup

// src/router.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

export function createAppRouter() {
  // Fresh QueryClient per request — prevents data leaking between SSR requests
  const queryClient = new QueryClient()

  return createRouter({
    routeTree,
    defaultPreloadStaleTime: 0,
    context: { queryClient },
    Wrap: ({ children }) => (
      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
    ),
  })
}

declare module '@tanstack/react-router' {
  interface Register {
    router: ReturnType<typeof createAppRouter>
  }
}

SSR with `setupRouterSsrQueryIntegration`

For automatic SSR dehydration/hydration and streaming:

npm install @tanstack/react-router-ssr-query

// src/router.tsx
import { QueryClient } from '@tanstack/react-query'
import { createRouter } from '@tanstack/react-router'
import { setupRouterSsrQueryIntegration } from '@tanstack/react-router-ssr-query'
import { routeTree } from './routeTree.gen'

export function createAppRouter() {
  const queryClient = new QueryClient()

  const router = createRouter({
    routeTree,
    defaultPreloadStaleTime: 0,
    context: { queryClient },
  })

  setupRouterSsrQueryIntegration({
    router,
    queryClient,
    // wrapQueryClient: true (default — wraps with QueryClientProvider)
    // handleRedirects: true (default — handles redirect() from queries)
  })

  return router
}

The integration:

Dehydrates query state on the server and hydrates on the client automatically
Streams queries that resolve during server render to the client
Handles redirect() thrown from queries/mutations

Manual SSR Dehydration/Hydration (Without SSR Query Package)

// src/router.tsx
import { QueryClient, dehydrate, hydrate } from '@tanstack/react-query'
import { QueryClientProvider } from '@tanstack/react-query'
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

export function createAppRouter() {
  const queryClient = new QueryClient()

  return createRouter({
    routeTree,
    defaultPreloadStaleTime: 0,
    context: { queryClient },
    dehydrate: () => ({
      queryClientState: dehydrate(queryClient),
    }),
    hydrate: (dehydrated) => {
      hydrate(queryClient, dehydrated.queryClientState)
    },
    Wrap: ({ children }) => (
      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
    ),
  })
}

Core Pattern: Static `query` in Loader + `useSuspenseQuery` in Component

This is the recommended pattern. The loader queries data before render (no loading flash), using staleTime: 'static' to reuse cached data without a stale refetch. The component subscribes to the cache for updates.

// src/routes/posts.tsx
import { queryOptions, useSuspenseQuery } from '@tanstack/react-query'
import { createFileRoute } from '@tanstack/react-router'

interface Post {
  id: string
  title: string
}

const postsQueryOptions = queryOptions({
  queryKey: ['posts'],
  queryFn: (): Promise<Array<Post>> =>
    fetch('/api/posts').then((r) => r.json()),
})

export const Route = createFileRoute('/posts')({
  loader: ({ context }) => {
    // query returns cached data when available and fetches when it is missing
    // Keep this query static so a stale refetch does not block navigation
    return context.queryClient.query({
      ...postsQueryOptions,
      staleTime: 'static',
    })
  },
  component: PostsPage,
})

function PostsPage() {
  // useSuspenseQuery subscribes to cache — gets background updates
  const { data: posts } = useSuspenseQuery(postsQueryOptions)

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

With Dynamic Params

// src/routes/posts/$postId.tsx
import { queryOptions, useSuspenseQuery } from '@tanstack/react-query'
import { createFileRoute } from '@tanstack/react-router'

interface Post {
  id: string
  title: string
  content: string
}

const postQueryOptions = (postId: string) =>
  queryOptions({
    queryKey: ['posts', postId],
    queryFn: () => fetch(`/api/posts/${postId}`).then((r) => r.json()),
  })

export const Route = createFileRoute('/posts/$postId')({
  loader: ({ context, params }) => {
    return context.queryClient.query({
      ...postQueryOptions(params.postId),
      staleTime: 'static',
    })
  },
  component: PostPage,
})

function PostPage() {
  const { postId } = Route.useParams()
  const { data: post } = useSuspenseQuery(postQueryOptions(postId))

  return <article>{post.title}</article>
}

Streaming Pattern: Fire-and-Forget `query` (Not Awaited)

For non-critical data, start a query without blocking navigation. Handle its rejection with noop so a background failure does not become an unhandled rejection:

import { noop, useQuery, useSuspenseQuery } from '@tanstack/react-query'

export const Route = createFileRoute('/dashboard')({
  loader: ({ context }) => {
    // Await critical data
    const user = context.queryClient.query({
      ...userQueryOptions,
      staleTime: 'static',
    })

    // Start non-critical query without awaiting — streams during SSR
    void context.queryClient.query({ ...analyticsQueryOptions }).catch(noop)

    return user
  },
  component: Dashboard,
})

function Dashboard() {
  // Critical: suspense (data ready immediately)
  const { data: user } = useSuspenseQuery(userQueryOptions)

  // Non-critical: regular query (shows loading state)
  const { data: analytics, isLoading } = useQuery(analyticsQueryOptions)

  return (
    <div>
      <h1>Welcome {user.name}</h1>
      {isLoading ? <Skeleton /> : <AnalyticsChart data={analytics} />}
    </div>
  )
}

Error Handling with `useQueryErrorResetBoundary`

import { useEffect } from 'react'
import { useQueryErrorResetBoundary } from '@tanstack/react-query'
import { useRouter } from '@tanstack/react-router'

export const Route = createFileRoute('/posts')({
  loader: ({ context }) =>
    context.queryClient.query({
      ...postsQueryOptions,
      staleTime: 'static',
    }),
  errorComponent: PostsErrorComponent,
  component: PostsPage,
})

function PostsErrorComponent({
  error,
  reset,
}: {
  error: unknown
  reset: () => void
}) {
  const router = useRouter()
  const queryErrorResetBoundary = useQueryErrorResetBoundary()

  useEffect(() => {
    queryErrorResetBoundary.reset()
  }, [queryErrorResetBoundary])

  return (
    <div>
      <p>{error instanceof Error ? error.message : String(error)}</p>
      <button onClick={() => router.invalidate()}>Retry</button>
    </div>
  )
}

Common Mistakes

1. HIGH: Not setting `defaultPreloadStaleTime` to 0

Router has a built-in preload cache (default staleTime for preloads is 30s). This prevents Query from controlling data freshness during preloading.

// WRONG — Router's preload cache serves stale data, Query never refetches
const router = createRouter({ routeTree })

// CORRECT — disable Router's preload cache, let Query manage freshness
const router = createRouter({
  routeTree,
  defaultPreloadStaleTime: 0,
})

2. HIGH: Creating QueryClient outside `createRouter` for SSR

A module-level singleton QueryClient is shared across all server requests, leaking user data between requests.

// WRONG — shared across SSR requests
const queryClient = new QueryClient()
export function createAppRouter() {
  return createRouter({
    routeTree,
    context: { queryClient },
  })
}

// CORRECT — new QueryClient per createAppRouter call
export function createAppRouter() {
  const queryClient = new QueryClient()
  return createRouter({
    routeTree,
    context: { queryClient },
  })
}

3. MEDIUM: Awaiting a fire-and-forget query in a loader blocks rendering

A query used for streaming should start in the background and handle errors with catch(noop). Awaiting it blocks the navigation transition until the data resolves, defeating the purpose of streaming.

import { noop } from '@tanstack/react-query'

// WRONG — blocks navigation, no streaming benefit
loader: async ({ context }) => {
  await context.queryClient.query({ ...analyticsQueryOptions }).catch(noop)
}

// CORRECT — fire and forget for streaming, with handled rejection
loader: ({ context }) => {
  void context.queryClient.query({ ...analyticsQueryOptions }).catch(noop)
}

// If you need to block (critical data), use a static query instead:
loader: ({ context }) => {
  return context.queryClient.query({
    ...criticalQueryOptions,
    staleTime: 'static',
  })
}

4. HIGH: Missing double parentheses on `createRootRouteWithContext`

createRootRouteWithContext<Type>() is a factory — it returns a function. The second call passes route options.

// WRONG — passing options to the factory, not the returned function
const rootRoute = createRootRouteWithContext<{ queryClient: QueryClient }>({
  component: RootComponent,
})

// CORRECT — double call: factory()({options})
const rootRoute = createRootRouteWithContext<{ queryClient: QueryClient }>()({
  component: RootComponent,
})

Tension: Built-In SWR Cache vs External Cache

TanStack Router has its own SWR cache (staleTime, gcTime, defaultPreloadStaleTime). When using Query as an external cache:

Set defaultPreloadStaleTime: 0 to prevent Router's cache from short-circuiting Query's freshness logic
Router's staleTime/gcTime still apply to the loader return value. For pure Query patterns, return nothing from the loader (just a static query for the side effect) and read data exclusively from useSuspenseQuery
router.invalidate() re-runs loaders (which call query with staleTime: 'static'), so the cached Query data remains the freshness authority

Cross-References

router-core/data-loading — built-in loader caching fundamentals
router-core/ssr — SSR setup for dehydration/hydration

router-query/SKILL.md