Initial commit
This commit is contained in:
Zhongwei Li
408
skills/router-query-integration/SKILL.md
Normal file
408
skills/router-query-integration/SKILL.md
Normal file
@@ -0,0 +1,408 @@
|
||||
---
|
||||
name: router-query-integration
|
||||
description: Integrate TanStack Router with TanStack Query for optimal data fetching. Covers route loaders with query prefetching, ensuring instant navigation, and eliminating request waterfalls. Use when setting up route loaders or optimizing navigation performance.
|
||||
---
|
||||
|
||||
# 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
|
||||
Reference in New Issue
Block a user