tanstack-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TanStack Integration — Strategic Library Adoption

TanStack集成——策略性库采用方案

Philosophy: Avoid "man with a hammer syndrome" (to whom everything appears as a nail). Start vanilla, then strategically adopt TanStack where it provides clear benefits.

Timing: Use this AFTER your app is already working pretty well in vanilla Next.js/React/Tailwind.

核心原则： 避免‘锤子综合征’（即手握锤子的人看什么都像钉子）。先使用原生技术实现，再在能明确带来收益的场景下策略性地采用TanStack。

时机： 仅在你的应用通过原生Next.js/React/Tailwind实现并正常运行后再使用此方案。

What is TanStack?

什么是TanStack？

TanStack is a set of high-quality libraries for web applications:

Library	Purpose
TanStack Query	Server state management, caching, synchronization
TanStack Table	Headless table/grid logic
TanStack Form	Form state management and validation
TanStack Router	Type-safe routing
TanStack Virtual	Virtualization for large lists
TanStack Ranger	Range/slider components

TanStack是一套面向Web应用的高质量库集合：

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

The Anti-Pattern: Premature Adoption

反模式：过早采用

Don't do this:

Start new project
Immediately install all TanStack libraries
Force everything through TanStack patterns
End up with over-engineered code

Why it's bad:

Not every feature needs TanStack
Adds complexity where simple solutions work
Makes code harder to understand for no benefit
"Man with a hammer" sees every problem as a nail

请勿这样做：

启动新项目
立即安装所有TanStack库
强行让所有功能适配TanStack模式
最终得到过度工程化的代码

为何不可取：

并非所有功能都需要TanStack
在简单方案可行的场景下增加复杂度
无端提升代码理解难度
陷入‘锤子综合征’，将所有问题都视为TanStack可解决的场景

The Correct Pattern: Strategic Adoption

正确模式：策略性采用

Do this instead:

Build with vanilla Next.js 16, React 19, Tailwind
Get the app working well
Run the TanStack analysis prompt
Adopt TanStack only where it clearly improves things
Repeat several rounds

正确做法：

使用原生Next.js 16、React 19、Tailwind构建应用
确保应用正常稳定运行
运行TanStack分析提示词
仅在能明确改进代码的场景下采用TanStack
重复多轮优化

THE EXACT PROMPT — TanStack Analysis

精准提示词——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

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

When to Use Each TanStack Library

各TanStack库的适用场景

TanStack Query

Good candidates:

API calls that need caching
Data that's fetched frequently
Optimistic updates
Background refetching
Pagination with caching
Infinite scroll

Skip if:

Simple one-time fetches
Static data
Data that doesn't need synchronization

适用场景：

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

不适用场景：

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

TanStack Table

Good candidates:

Complex data tables with sorting/filtering
Tables with pagination
Column resizing/reordering
Row selection
Expandable rows
Server-side data tables

Skip if:

Simple static tables
Tables with < 20 rows
No interactivity needed

适用场景：

带排序/过滤的复杂数据表格
带分页的表格
列可调整大小/重新排序的表格
行选择功能
可展开行的表格
服务端渲染的数据表格

不适用场景：

简单静态表格
行数少于20的表格
无需交互的表格

TanStack Form

Good candidates:

Complex multi-step forms
Forms with complex validation
Forms with dynamic fields
Forms with async validation
Wizard-style workflows

Skip if:

Simple contact forms
Forms with 3-4 fields
Basic validation needs

适用场景：

复杂的多步骤表单
带复杂验证规则的表单
带动态字段的表单
带异步验证的表单
向导式流程表单

不适用场景：

简单联系表单
仅3-4个字段的表单
基础验证需求的表单

TanStack Router

Good candidates:

Large apps needing type-safe routing
Complex nested routes
Route-based code splitting
Search params management

Skip if:

Using Next.js App Router (already good)
Simple navigation needs
Few routes

适用场景：

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

不适用场景：

已使用Next.js App Router（功能已足够完善）
简单导航需求
路由数量少的应用

TanStack Virtual

Good candidates:

Lists with 1000+ items
Infinite scroll views
Large data grids
Chat message lists

Skip if:

Lists with < 100 items
Already using windowing elsewhere
Performance is fine without it

适用场景：

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

不适用场景：

少于100条数据的列表
已在其他地方使用窗口化技术
无性能问题的场景

Integration Workflow

集成工作流程

Step 1: Get App Working

步骤1：确保应用正常运行

Build your app with vanilla patterns first:

```
fetch
```
or axios for API calls
Native form handling
Simple HTML tables
Next.js routing

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

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

Step 2: Run Analysis

步骤2：运行分析

Use the TanStack analysis prompt with Claude Code + Opus 4.5 or Codex + GPT 5.2 (High reasoning effort).

结合Claude Code + Opus 4.5或Codex + GPT 5.2（高推理能力）运行TanStack分析提示词。

Step 3: Evaluate Suggestions

步骤3：评估建议

The model will identify opportunities. For each:

Does the complexity justify the benefit?
Is the current solution actually problematic?
Will this improve maintainability?

AI模型会识别优化机会，针对每个建议需评估：

引入的复杂度是否能带来对等收益？
当前实现是否真的存在问题？
这是否能提升代码可维护性？

Step 4: Selective Adoption

步骤4：选择性采用

Only adopt where there's clear benefit. It's fine to:

Use TanStack Query but not Table
Use Table for one complex table, not all tables
Mix vanilla and TanStack approaches

仅在有明确收益的场景下采用TanStack。以下做法是可行的：

使用TanStack Query但不使用Table
仅为一个复杂表格使用Table，而非所有表格
混合原生实现和TanStack方案

Step 5: Repeat

步骤5：重复优化

Run the analysis again after changes. New opportunities may emerge.

在修改后再次运行分析，可能会发现新的优化机会。

Best Models for This Task

适用于此任务的最佳模型

Model	Configuration
Claude Code + Opus 4.5	Use ultrathink
Codex + GPT 5.2	High or Extra-High reasoning effort

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

Example Improvements

优化示例

Before: Manual Data Fetching

优化前：手动数据获取

typescript

// 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));
}, []);

typescript

// 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));
}, []);

After: TanStack Query

优化后：使用TanStack Query

typescript

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

Benefits:

Built-in caching
Automatic refetching
Request deduplication
DevTools support

typescript

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

收益：

内置缓存功能
自动重新获取数据
请求去重
支持开发工具

Before: Complex Table Logic

优化前：复杂表格逻辑

typescript

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

typescript

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

After: TanStack Table

优化后：使用TanStack Table

typescript

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

Benefits:

Headless (you control the UI)
All table logic handled
Consistent behavior
Much less code

typescript

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

收益：

无头架构（完全控制UI）
所有表格逻辑已封装
行为一致性
代码量大幅减少

Creating Beads for TanStack Work

创建TanStack任务项

bash

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

bash

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

Complete Prompt Reference

完整提示词参考

TanStack Analysis

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

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

Focused Query Analysis

聚焦Query分析

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 data fetching patterns that would benefit from TanStack Query. Consider caching needs, refetching patterns, and optimistic updates. Identify the top 3 opportunities. Use ultrathink.

Focused Table Analysis

聚焦Table分析

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.

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.

Tips

小贴士

Don't over-adopt — Some vanilla patterns are fine
Measure the benefit — Does it actually improve the code?
Consider team familiarity — TanStack has a learning curve
Check bundle size — Only import what you need
Read the docs — TanStack documentation is excellent

不要过度采用——部分原生实现方案已经足够好
衡量收益——是否真的能改进代码？
考虑团队熟悉度——TanStack有一定学习曲线
检查包体积——仅导入所需的部分
阅读文档——TanStack的文档非常完善