tanstack-integration

TanStack 集成 — 战略性采用库

理念： 避免“手里拿着锤子，看什么都像钉子”的思维。先使用原生方案，再在能明确带来收益的地方战略性地采用 TanStack。

时机： 在你的应用已经基于原生 Next.js/React/Tailwind 运行良好后，再使用本指南。

---

什么是 TanStack？

TanStack 是一组适用于 Web 应用的高质量库：

库	用途
TanStack Query	服务端状态管理、缓存、同步
TanStack Table	无头表格/网格逻辑
TanStack Form	表单状态管理与验证
TanStack Router	类型安全的路由
TanStack Virtual	大型列表的虚拟化
TanStack Ranger	范围/滑块组件

---

反模式：过早采用

不要这样做：

1. 启动新项目
2. 立即安装所有 TanStack 库
3. 强行让所有内容都遵循 TanStack 模式
4. 最终得到过度设计的代码

这样做的问题：

• 并非每项功能都需要 TanStack
• 简单方案就能奏效的地方，却增加了复杂性
• 没有任何收益，反而让代码更难理解
• “手里拿着锤子”的人会把所有问题都看成钉子

---

正确模式：战略性采用

改为这样做：

1. 使用原生 Next.js 16、React 19、Tailwind 构建
2. 让应用顺利运行
3. 运行 TanStack 分析提示词
4. 只在能明确改善效果的地方采用 TanStack
5. 重复进行几轮

---

精确提示词 — TanStack 分析

Ok, I want you to look through the ENTIRE project and look for areas where, if we leveraged one of the many TanStack libraries (e.g., query, table, forms, etc), we could make part of the code much better, simpler, more performant, more maintainable, elegant, shorter, more reliable, etc. Use ultrathink

---

何时使用各个 TanStack 库

TanStack Query

适用场景：

• 需要缓存的 API 调用
• 频繁获取的数据
• 乐观更新
• 后台重新获取数据
• 带缓存的分页
• 无限滚动

不适用场景：

• 简单的一次性获取
• 静态数据
• 无需同步的数据

TanStack Table

适用场景：

• 带排序/筛选功能的复杂数据表
• 带分页的表格
• 列宽调整/重新排序
• 行选择
• 可展开的行
• 服务端数据表

不适用场景：

• 简单的静态表格
• 少于 20 行的表格
• 无需交互功能

TanStack Form

适用场景：

• 复杂的多步骤表单
• 带复杂验证的表单
• 带动态字段的表单
• 带异步验证的表单
• 向导式工作流

不适用场景：

• 简单的联系表单
• 只有 3-4 个字段的表单
• 仅需基本验证的场景

TanStack Router

适用场景：

• 需要类型安全路由的大型应用
• 复杂的嵌套路由
• 基于路由的代码拆分
• 搜索参数管理

不适用场景：

• 使用 Next.js App Router（本身已经很好用）
• 简单的导航需求
• 路由数量较少

TanStack Virtual

适用场景：

• 包含 1000+ 项的列表
• 无限滚动视图
• 大型数据网格
• 聊天消息列表

不适用场景：

• 少于 100 项的列表
• 已在其他地方使用窗口化
• 不使用它时性能也很好

---

集成工作流

第 1 步：让应用运行起来

先使用原生模式构建应用：

• 使用 fetch 或 axios 调用 API
• 原生表单处理
• 简单的 HTML 表格
• Next.js 路由

第 2 步：运行分析

将 TanStack 分析提示词与 Claude Code + Opus 4.5 或 Codex + GPT 5.2（高推理力度）搭配使用。

第 3 步：评估建议

模型会指出可以改进的地方。对于每一项，请考虑：

• 这种复杂性是否值得带来的收益？
• 当前方案是否真的存在问题？
• 这会改善可维护性吗？

第 4 步：有选择地采用

只在有明确收益的地方采用。以下做法都没问题：

• 使用 TanStack Query，但不使用 TanStack Table
• 只在一个复杂表格中使用 Table，而不是在所有表格中使用
• 混合使用原生方案和 TanStack 方案

第 5 步：重复分析

更改后再次运行分析。可能会发现新的机会。

---

适合此任务的模型

模型	配置
Claude Code + Opus 4.5	使用 ultrathink
Codex + GPT 5.2	高或特高推理力度

---

示例改进

之前：手动获取数据

// Vanilla approach
const [data, setData] = useState(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);

useEffect(() => {
  fetch('/api/users')
    .then(res => res.json())
    .then(setData)
    .catch(setError)
    .finally(() => setLoading(false));
}, []);

之后：TanStack Query

// TanStack Query approach
const { data, isLoading, error } = useQuery({
  queryKey: ['users'],
  queryFn: () => fetch('/api/users').then(res => res.json()),
});

优点：

• 内置缓存
• 自动重新获取
• 请求去重
• 支持 DevTools

之前：复杂的表格逻辑

// Vanilla approach with manual sorting, filtering, pagination
// ... 200+ lines of state management

之后：TanStack Table

// TanStack Table handles sorting, filtering, pagination
const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getSortedRowModel: getSortedRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
});

优点：

• 无头模式（由你控制 UI）
• 处理所有表格逻辑
• 行为一致
• 代码大幅减少

---

为 TanStack 工作创建 Beads

br create "Evaluate TanStack Query opportunities" -t enhancement -p 3
br create "Migrate user data fetching to TanStack Query" -t enhancement -p 2
br create "Implement data table with TanStack Table" -t feature -p 2
br create "Add TanStack Virtual to chat message list" -t performance -p 2

---

完整提示词参考

TanStack 分析

Ok, I want you to look through the ENTIRE project and look for areas where, if we leveraged one of the many TanStack libraries (e.g., query, table, forms, etc), we could make part of the code much better, simpler, more performant, more maintainable, elegant, shorter, more reliable, etc. Use ultrathink

定向查询分析

Look through the project for data fetching patterns that would benefit from TanStack Query. Consider caching needs, refetching patterns, and optimistic updates. Identify the top 3 opportunities. Use ultrathink.

定向表格分析

Look through the project for table/grid components that would benefit from TanStack Table. Consider sorting, filtering, pagination, and column management needs. Identify candidates. Use ultrathink.

---

提示

1. 不要过度采用 — 一些原生模式也完全可行
2. 衡量收益 — 它真的能改进代码吗？
3. 考虑团队熟悉度 — TanStack 有一定的学习曲线
4. 检查包大小 — 只导入所需内容
5. 阅读文档 — TanStack 文档非常出色