Back to Details

tanstack-integration-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

TanStack Integration Best Practices

TanStack 集成最佳实践

Guidelines for integrating TanStack Query, Router, and Start together effectively. These patterns ensure optimal data flow, caching coordination, and type safety across the stack.
有效集成TanStack Query、Router和Start的指南。这些模式可确保全栈范围内的最优数据流、缓存协调和类型安全。

When to Apply

适用场景

  • Setting up a new TanStack Start project
  • Integrating TanStack Query with TanStack Router
  • Configuring SSR with query hydration
  • Coordinating caching between router and query
  • Setting up type-safe data fetching patterns
  • 搭建新的TanStack Start项目
  • 将TanStack Query与TanStack Router集成
  • 配置带查询水合的SSR
  • 协调路由与查询之间的缓存
  • 搭建类型安全的数据获取模式

Rule Categories by Priority

按优先级划分的规则类别

PriorityCategoryRulesImpact
CRITICALSetup3 rulesFoundational configuration
CRITICALSSR Integration1 ruleRouter + Query SSR setup
HIGHData Flow4 rulesCorrect data fetching patterns
MEDIUMCaching3 rulesPerformance optimization
MEDIUMSSR2 rulesAdditional SSR patterns
优先级类别规则数量影响
关键基础设置3条规则基础配置
关键SSR集成1条规则路由 + 查询SSR设置
高数据流4条规则正确的数据获取模式
中缓存3条规则性能优化
中SSR补充2条规则额外的SSR模式

Quick Reference

快速参考

Setup (Prefix: 
setup-
)

基础设置（前缀：
setup-
）

  • setup-query-client-context
    — Pass QueryClient through router context
  • setup-provider-wrapping
    — Correctly wrap with QueryClientProvider
  • setup-stale-time-coordination
    — Coordinate staleTime between router and query
  • setup-query-client-context
    — 通过路由上下文传递QueryClient
  • setup-provider-wrapping
    — 正确使用QueryClientProvider进行包裹
  • setup-stale-time-coordination
    — 协调路由与查询之间的staleTime

Data Flow (Prefix: 
flow-
)

数据流（前缀：
flow-
）

  • flow-loader-query-pattern
    — Use loaders with ensureQueryData
  • flow-suspense-query-component
    — Use useSuspenseQuery in components
  • flow-mutations-invalidation
    — Coordinate mutations with query invalidation
  • flow-server-functions-queries
    — Use server functions for query functions
  • flow-loader-query-pattern
    — 将加载器与ensureQueryData配合使用
  • flow-suspense-query-component
    — 在组件中使用useSuspenseQuery
  • flow-mutations-invalidation
    — 协调变更操作与查询失效
  • flow-server-functions-queries
    — 将服务器函数用于查询函数

Caching (Prefix: 
cache-
)

缓存（前缀：
cache-
）

  • cache-single-source
    — Let TanStack Query manage caching
  • cache-preload-coordination
    — Coordinate preloading between router and query
  • cache-invalidation-patterns
    — Unified invalidation patterns
  • cache-single-source
    — 让TanStack Query管理缓存
  • cache-preload-coordination
    — 协调路由与查询之间的预加载
  • cache-invalidation-patterns
    — 统一的失效模式

SSR Integration (Prefix: 
ssr-
)

SSR集成（前缀：
ssr-
）

  • ssr-dehydrate-hydrate
    — Use setupRouterSsrQueryIntegration for automatic SSR
  • ssr-dehydrate-hydrate
    — 使用setupRouterSsrQueryIntegration实现自动SSR

Additional SSR (Prefix: 
ssr-
)

SSR补充（前缀：
ssr-
）

  • ssr-per-request-client
    — Create QueryClient per request
  • ssr-streaming-queries
    — Handle streaming with queries
  • ssr-per-request-client
    — 为每个请求创建QueryClient
  • ssr-streaming-queries
    — 处理带查询的流式传输

How to Use

使用方法

Each rule file in the 
rules/
directory contains:
  1. Explanation — Why this pattern matters
  2. Bad Example — Anti-pattern to avoid
  3. Good Example — Recommended implementation
  4. Context — When to apply or skip this rule
rules/
目录下的每个规则文件包含：
  1. 说明 — 该模式的重要性
  2. 反面示例 — 需要避免的反模式
  3. 正面示例 — 推荐的实现方式
  4. 适用场景 — 何时应用或跳过该规则

Full Reference

完整参考

See individual rule files in 
rules/
directory for detailed guidance and code examples.
请查看
rules/
目录下的单个规则文件，获取详细指导和代码示例。