tanstack-integration-best-practices 是做什麼的？
整合 TanStack Query、TanStack Router 與 TanStack Start 的最佳實務。涵蓋全端資料流、伺服器端渲染（SSR）及快取協調的設計模式。
核心原則
- 以查詢鍵為中心：使用一致的查詢鍵結構，讓 Router 與 Query 能協調快取。
- 伺服器端預取：在 Router 的載入器中預取 Query 資料，實現無閃爍（flash-free）的頁面導航。
- 快取同步：透過 TanStack Start 的伺服器函式（server functions）變更資料後，自動失效 Query 快取。
支援的平台
- React (TanStack Router + TanStack Query)
- Solid (Solid Router + TanStack Query)
- 任何支援 TanStack Start 的全端框架
建議模式
1. 共用查詢鍵工廠
// lib/query-keys.ts
export const queryKeys = {
posts: {
all: ['posts'] as const,
byId: (id: string) => ['posts', id] as const,
},
}
2. 使用 Router 載入器預取
// routes/posts.$id.tsx
import { queryOptions, prefetchQuery } from '@tanstack/react-query'
import { createFileRoute } from '@tanstack/react-router'
const postQueryOptions = (id: string) =>
queryOptions({
queryKey: queryKeys.posts.byId(id),
queryFn: () => fetchPost(id),
})
export const Route = createFileRoute('/posts/$id')({
loader: async ({ context, params }) => {
await context.queryClient.prefetchQuery(postQueryOptions(params.id))
return { id: params.id }
},
})
3. 伺服器函式中使快取失效
// server/actions.ts
import { server$, useServerFn } from '@tanstack/start'
import { invalidateQueries } from '@tanstack/react-query'
export const updatePost = server$(async (data: PostData) => {
// 更新資料庫
await db.post.update(data)
// 失效相關查詢
return { success: true }
})
常見陷阱
- 重複請求：確保 Router 載入器與 Query 元件不要同時發起相同請求。使用
prefetchQuery統一管理。 - 快取過期：在資料變更後，手動呼叫
invalidateQueries避免用戶看到舊資料。 - SSR 狀態水位：用 TanStack Start 的
Dehydrate元件正確傳遞序列化後的快取狀態。