tanstack-frontend

TanStack 前端模式

概述

使用项目标准的 TRPC 集成、加载器策略、类型推断和表单处理来实现 TanStack Router 路由。请依据本文档中的决策规则，并参阅 references/ 中的完整示例。

核心模式

1) 使用加载器驱动的数据策略定义路由

• 使用 createFileRoute(...) 定义每个路由，并通过加载器预加载关键数据。
• 在组件中通过路由 API（Route.useParams()、Route.useSearch()）读取参数和搜索参数。
• 示例见 references/router-loader-examples.md。

2) 有意选择加载器预取策略

• 对于首屏渲染所需的数据，使用 await prefetchQuery(...)。
• 对于多个关键查询，使用 await Promise.all([...])。
• 仅对次要数据使用 void prefetchQuery(...)。
• 当加载器逻辑需要返回数据时，使用 fetchQuery(...)。
• 同时遵循 void 规则和下文的 Suspense 规则。

完整的决策流程和性能权衡见 references/prefetch-patterns.md。

3) 为 void 预取的数据设置 Suspense 边界

• 使用 useSuspenseQuery(...) 消费 void prefetchQuery(...) 数据的每个组件，都必须用 <Suspense> 包裹。
• 将缺少边界视为正确性错误（存在 hydration 风险），而非可选的优化。
• 最终确定路由前，核对每个 void 决策是否符合此要求。

示例和加载器模式决策表见 references/prefetch-patterns.md。

4) 应用 TRPC v11 TanStack Query 模式

统一使用以下规则：

• 将 TanStack Query hooks（useQuery、useSuspenseQuery、useMutation）与 TRPC 工厂方法搭配使用。
• 查询和预取使用 .queryOptions(...)，变更使用 .mutationOptions(...)。
• 使用 .queryKey(...) 使缓存失效。
• 不要在 TRPC procedures 上调用 .useQuery() 或 .useMutation()。

简明的正确与错误示例见 references/trpc-v11-query-pattern.md。

5) 推断类型时优先使用 RouterInputs/RouterOutputs

• 在路由组件和辅助函数中，输入和响应类型优先使用 RouterInputs/RouterOutputs。
• 如果显式本地类型表示仅用于 UI 的视图模型、外部库契约，或有意进行且不对应服务器载荷的收窄或聚合，则可以使用。
• 避免将原始 TRPC 响应结构重复定义为手写应用类型。

实用的类型推断模式见 references/type-inference.md。

6) 使用项目的表单封装（而非原始 TanStack Form）

• 在此模板中，“TanStack Form”指 useAppForm + @/shared/forms/* 字段组件。
• 使用共享表单组件组合表单，并显式传递 form/field。
• 除非正在更新共享表单基础设施本身，否则避免在功能代码中使用原始 TanStack Form hooks。

完整的表单模式见 references/form-patterns.md。

7) 遵循前端约定

• 组件属性优先使用 type Props = ... 命名。
• 使用绝对导入（@/...）。
• 从 @project/common 导入跨包共享类型。
• 通过 queryKey(...) 辅助函数使 TRPC 缓存失效。

资源

references/

• router-loader-examples.md - 完整的路由定义示例
• prefetch-patterns.md - 性能优化和预取策略
• trpc-v11-query-pattern.md - 精简的 TRPC v11 查询、变更和缓存失效规则
• form-patterns.md - 带验证示例的表单处理
• type-inference.md - TRPC 类型推断模式和示例