router-query-integration
Use when setting up route loaders or optimizing navigation performance. Integrates TanStack Router with TanStack Query for optimal data fetching. Covers route loaders with query prefetching, ensuring instant navigation, and eliminating request waterfalls.
Source facts
- Repository
- MadAppGang/claude-code
- Last source activity
- January 20, 2026 at 08:16
- Detected SKILL.md language
- English
- Stars
- 284
- Forks
- 25
Install options
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Review the source files
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Showing SKILL.md
SKILL.md
Source instructions · Read-only preview- name
- router-query-integration
- description
- Use when setting up route loaders or optimizing navigation performance. Integrates TanStack Router with TanStack Query for optimal data fetching. Covers route loaders with query prefetching, ensuring instant navigation, and eliminating request waterfalls.
- updated
- 2026-01-20T00:00:00.000Z
- keywords
- tanstack-router, tanstack-query, route-loaders, prefetching, navigation, query-options
# Router × Query Integration
Seamlessly integrate TanStack Router with TanStack Query for optimal SPA performance and instant navigation.
## Route Loader + Query Prefetch
The key pattern: Use route loaders to prefetch queries BEFORE navigation completes.
**Benefits:**
- Loaders run before render, eliminating waterfall
- Fast SPA navigations (instant perceived performance)
- Queries still benefit from cache deduplication
- Add Router & Query DevTools during development (auto-hide in production)
## Basic Pattern
```typescript
// src/routes/users/$id.tsx
import { createFileRoute } from '@tanstack/react-router'
import { queryClient } from '@/app/queryClient'
import { usersKeys, fetchUser } from '@/features/users/queries'
export const Route = createFileRoute('/users/$id')({
loader: async ({ params }) => {
const id = params.id
return queryClient.ensureQueryData({
queryKey: usersKeys.detail(id),
queryFn: () => fetchUser(id),
staleTime: 30_000, // Fresh for 30 seconds
})
},
component: UserPage,
})
function UserPage() {
const { id } = Route.useParams()
const { data: user } = useQuery({
queryKey: usersKeys.detail(id),
queryFn: () => fetchUser(id),
})
// Data is already loaded from loader, so this returns instantly
return <div>{user.name}</div>
}
```
## Using Query Options Pattern (Recommended)
**Query Options** provide maximum type safety and DRY:
```typescript
// features/users/queries.ts
import { queryOptions } from '@tanstack/react-query'
export function userQueryOptions(userId: string) {
return queryOptions({
queryKey: ['users', userId],
queryFn: () => fetchUser(userId),
staleTime: 30_000,
})
}
export function useUser(userId: string) {
return useQuery(userQueryOptions(userId))
}
// src/routes/users/$userId.tsx
import { userQueryOptions } from '@/features/users/queries'
import { queryClient } from '@/app/queryClient'
export const Route = createFileRoute('/users/$userId')({
loader: ({ params }) =>
queryClient.ensureQueryData(userQueryOptions(params.userId)),
component: UserPage,
})
function UserPage() {
const { userId } = Route.useParams()
const { data: user } = useUser(userId)
return <div>{user.name}</div>
}
```
## Multiple Queries in Loader
```typescript
export const Route = createFileRoute('/dashboard')({
loader: async () => {
// Run in parallel
await Promise.all([
queryClient.ensureQueryData(userQueryOptions()),
queryClient.ensureQueryData(statsQueryOptions()),
queryClient.ensureQueryData(postsQueryOptions()),
])
},
component: Dashboard,
})
function Dashboard() {
const { data: user } = useUser()
const { data: stats } = useStats()
const { data: posts } = usePosts()
// All data pre-loaded, renders instantly
return (
<div>
<UserHeader user={user} />
<StatsPanel stats={stats} />
<PostsList posts={posts} />
</div>
)
}
```
## Dependent Queries
```typescript
export const Route = createFileRoute('/users/$userId/posts')({
loader: async ({ params }) => {
// First ensure user data
const user = await queryClient.ensureQueryData(
userQueryOptions(params.userId)
)
// Then fetch user's posts
return queryClient.ensureQueryData(
userPostsQueryOptions(user.id)
)
},
component: UserPostsPage,
})
```
## Query Client Setup
**Export the query client for use in loaders:**
```typescript
// src/app/queryClient.ts
import { QueryClient } from '@tanstack/react-query'
export const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 0,
gcTime: 5 * 60_000,
retry: 1,
},
},
})
// src/main.tsx
import { QueryClientProvider } from '@tanstack/react-query'
import { queryClient } from './app/queryClient'
ReactDOM.createRoot(document.getElementById('root')!).render(
<StrictMode>
<QueryClientProvider client={queryClient}>
<RouterProvider router={router} />
</QueryClientProvider>
</StrictMode>
)
```
## Prefetch vs Ensure
**`prefetchQuery`** - Fire and forget, don't wait:
```typescript
loader: ({ params }) => {
// Don't await - just start fetching
queryClient.prefetchQuery(userQueryOptions(params.userId))
// Navigation continues immediately
}
```
**`ensureQueryData`** - Wait for data (recommended):
```typescript
loader: async ({ params }) => {
// Await - navigation waits until data is ready
return await queryClient.ensureQueryData(userQueryOptions(params.userId))
}
```
**`fetchQuery`** - Always fetches fresh:
```typescript
loader: async ({ params }) => {
// Ignores cache, always fetches
return await queryClient.fetchQuery(userQueryOptions(params.userId))
}
```
**Recommendation:** Use `ensureQueryData` for most cases - respects cache and staleTime.
## Handling Errors in Loaders
```typescript
export const Route = createFileRoute('/users/$userId')({
loader: async ({ params }) => {
try {
return await queryClient.ensureQueryData(userQueryOptions(params.userId))
} catch (error) {
// Let router error boundary handle it
throw error
}
},
errorComponent: ({ error }) => (
<div>
<h1>Failed to load user</h1>
<p>{error.message}</p>
</div>
),
component: UserPage,
})
```
## Invalidating Queries After Mutations
```typescript
// features/users/mutations.ts
export function useUpdateUser() {
const queryClient = useQueryClient()
const navigate = useNavigate()
return useMutation({
mutationFn: (user: UpdateUserDTO) => api.put(`/users/${user.id}`, user),
onSuccess: (updatedUser) => {
// Update cache immediately
queryClient.setQueryData(
userQueryOptions(updatedUser.id).queryKey,
updatedUser
)
// Invalidate related queries
queryClient.invalidateQueries({ queryKey: ['users', 'list'] })
// Navigate to updated user page (will use cached data)
navigate({ to: '/users/$userId', params: { userId: updatedUser.id } })
},
})
}
```
## Preloading on Link Hover
```typescript
import { Link, useRouter } from '@tanstack/react-router'
function UserLink({ userId }: { userId: string }) {
const router = useRouter()
const handleMouseEnter = () => {
// Preload route (includes loader)
router.preloadRoute({ to: '/users/$userId', params: { userId } })
}
return (
<Link
to="/users/$userId"
params={{ userId }}
onMouseEnter={handleMouseEnter}
>
View User
</Link>
)
}
```
Or use built-in preload:
```typescript
<Link
to="/users/$userId"
params={{ userId: '123' }}
preload="intent" // Preload on hover/focus
>
View User
</Link>
```
## Search Params + Queries
```typescript
// src/routes/users/index.tsx
import { z } from 'zod'
const searchSchema = z.object({
page: z.number().default(1),
filter: z.enum(['active', 'all']).default('all'),
})
export const Route = createFileRoute('/users/')({
validateSearch: searchSchema,
loader: ({ search }) => {
return queryClient.ensureQueryData(
usersListQueryOptions(search.page, search.filter)
)
},
component: UsersPage,
})
function UsersPage() {
const { page, filter } = Route.useSearch()
const { data: users } = useUsersList(page, filter)
return <UserTable users={users} page={page} filter={filter} />
}
```
## Suspense Mode
With Suspense, you don't need separate loading states:
```typescript
export const Route = createFileRoute('/users/$userId')({
loader: ({ params }) =>
queryClient.ensureQueryData(userQueryOptions(params.userId)),
component: UserPage,
})
function UserPage() {
const { userId } = Route.useParams()
// Use Suspense hook - data is NEVER undefined
const { data: user } = useSuspenseQuery(userQueryOptions(userId))
return <div>{user.name}</div>
}
// Wrap route in Suspense boundary (in __root.tsx or layout)
<Suspense fallback={<Spinner />}>
<Outlet />
</Suspense>
```
## Performance Best Practices
1. **Prefetch in Loaders** - Always use loaders to eliminate waterfalls
2. **Use Query Options** - Share configuration between loaders and components
3. **Set Appropriate staleTime** - Tune per query (30s for user data, 10min for static)
4. **Parallel Prefetching** - Use `Promise.all()` for independent queries
5. **Hover Preloading** - Enable `preload="intent"` on critical links
6. **Cache Invalidation** - Be specific with invalidation keys to avoid unnecessary refetches
## DevTools Setup
```typescript
// src/main.tsx
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import { TanStackRouterDevtools } from '@tanstack/router-devtools'
<QueryClientProvider client={queryClient}>
<RouterProvider router={router} />
<ReactQueryDevtools position="bottom-right" />
<TanStackRouterDevtools position="bottom-left" />
</QueryClientProvider>
```
Both auto-hide in production.
## Common Patterns
**List + Detail Pattern:**
```typescript
// List route prefetches list
export const ListRoute = createFileRoute('/users/')({
loader: () => queryClient.ensureQueryData(usersListQueryOptions()),
component: UsersList,
})
// Detail route prefetches specific user
export const DetailRoute = createFileRoute('/users/$userId')({
loader: ({ params }) =>
queryClient.ensureQueryData(userQueryOptions(params.userId)),
component: UserDetail,
})
// Clicking from list to detail uses cached data if available
```
**Edit Form Pattern:**
```typescript
export const EditRoute = createFileRoute('/users/$userId/edit')({
loader: ({ params }) =>
queryClient.ensureQueryData(userQueryOptions(params.userId)),
component: UserEditForm,
})
function UserEditForm() {
const { userId } = Route.useParams()
const { data: user } = useUser(userId)
const updateUser = useUpdateUser()
// Form pre-populated with cached user data
return <Form initialValues={user} onSubmit={updateUser.mutate} />
}
```
## Related Skills
- **tanstack-query** - Comprehensive Query v5 patterns
- **tanstack-router** - Router configuration and usage
- **api-integration** - OpenAPI + Apidog patterns
View on GitHub