tanstack-suite

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TanStack Suite Skill

TanStack Suite 技能指南

Use this skill when you’re building or maintaining apps with the TanStack ecosystem, especially when you need:

Correct package selection (core vs adapter vs devtools)
Version alignment across related packages
Correct SSR/data-loading and hydration behavior
Performance best practices (tables, lists, routers)
Devtools setup and debugging workflows

This skill covers:

TanStack Start (full-stack React meta-framework)
TanStack Router (type-safe routing)
TanStack Query (async server-state)
TanStack Table (headless tables/datagrids)
TanStack DB (reactive client DB + sync)
TanStack Store (signals-like reactive store)
TanStack Virtual (virtualized lists/grids)
TanStack Pacer (debounce/throttle/rate-limit/queue/batch utilities)
TanStack Form (type-safe form state + validation)
TanStack AI (type-safe AI SDK + tool calling + streaming)
TanStack Devtools (unified devtools panel + plugins)

当你基于TanStack生态系统构建或维护应用时，可以使用本技能，尤其是在你需要以下支持的场景：

正确的包选择（核心包 vs 适配包 vs 开发工具包）
相关包之间的版本对齐
正确的SSR/数据加载与水合行为
性能最佳实践（表格、列表、路由）
开发工具的配置与调试流程

本技能涵盖以下内容：

TanStack Start（全栈React元框架）
TanStack Router（类型安全路由）
TanStack Query（异步服务端状态管理）
TanStack Table（无表头表格/数据网格）
TanStack DB（响应式客户端数据库 + 同步功能）
TanStack Store（类信号的响应式状态存储）
TanStack Virtual（虚拟化列表/网格）
TanStack Pacer（防抖/节流/速率限制/队列/批处理工具）
TanStack Form（类型安全表单状态 + 验证）
TanStack AI（类型安全AI SDK + 工具调用 + 流式传输）
TanStack Devtools（统一开发工具面板 + 插件）

How to use this skill

如何使用本技能

1) Identify the project archetype

1) 确定项目原型

Pick the closest archetype before writing code:

TanStack Start app (recommended when you control the full stack)
React + Vite app (add Router/Query/etc manually)
Monorepo (workspace version alignment is critical)

在编写代码前，选择最匹配的项目原型：

TanStack Start应用（当你控制整个技术栈时推荐使用）
React + Vite应用（手动添加Router/Query等工具）
单体仓库（工作区版本对齐至关重要）

2) Run the audit scripts early

2) 尽早运行审计脚本

From the project root, run:

bash

node path/to/skill/scripts/tanstack-audit.mjs
node path/to/skill/scripts/tanstack-usage-report.mjs
node path/to/skill/scripts/tanstack-router-plugin-check.mjs
node path/to/skill/scripts/tanstack-devtools-snippet.mjs

These scripts are read-only and help you quickly detect:

Which TanStack packages are installed
Common version-mismatch footguns
Whether Router file-based generation is configured
A ready-to-paste Devtools setup snippet based on installed plugins

从项目根目录运行以下命令：

bash

node path/to/skill/scripts/tanstack-audit.mjs
node path/to/skill/scripts/tanstack-usage-report.mjs
node path/to/skill/scripts/tanstack-router-plugin-check.mjs
node path/to/skill/scripts/tanstack-devtools-snippet.mjs

这些脚本为只读模式，可帮助你快速检测：

已安装的TanStack包
常见的版本不匹配问题
是否配置了Router的文件路由生成功能
基于已安装插件生成的可直接粘贴的Devtools配置代码段

3) Load the smallest relevant reference doc

3) 加载最小化的相关参考文档

This skill includes package-specific reference docs under

references/

. Load only what you need:

```
references/tanstack-start.md
```
```
references/tanstack-router.md
```
```
references/tanstack-query.md
```
```
references/tanstack-table.md
```
```
references/tanstack-db.md
```
```
references/tanstack-store.md
```
```
references/tanstack-virtual.md
```
```
references/tanstack-pacer.md
```
```
references/tanstack-form.md
```
```
references/tanstack-ai.md
```
```
references/tanstack-devtools.md
```
```
references/versioning-and-packages.md
```

本技能在

references/

目录下包含了各包的专属参考文档。仅加载你需要的内容：

```
references/tanstack-start.md
```
```
references/tanstack-router.md
```
```
references/tanstack-query.md
```
```
references/tanstack-table.md
```
```
references/tanstack-db.md
```
```
references/tanstack-store.md
```
```
references/tanstack-virtual.md
```
```
references/tanstack-pacer.md
```
```
references/tanstack-form.md
```
```
references/tanstack-ai.md
```
```
references/tanstack-devtools.md
```
```
references/versioning-and-packages.md
```

Operating principles

操作原则

Prefer official adapters + idiomatic patterns

优先使用官方适配器 + 惯用模式

Prefer framework adapters (e.g.
```
@tanstack/react-query
```
,
```
@tanstack/react-router
```
,
```
@tanstack/react-table
```
) over lower-level core packages unless you’re authoring an adapter.
Use file-based routing and generated route trees where supported; avoid hand-maintaining giant route configs.

优先使用框架适配器（例如
```
@tanstack/react-query
```
、
```
@tanstack/react-router
```
、
```
@tanstack/react-table
```
）而非底层核心包，除非你正在开发一个适配器。
在支持的场景下，使用文件路由和生成式路由树；避免手动维护庞大的路由配置。

Keep versions aligned

保持版本对齐

Some TanStack package families are designed to move together.

Router + Start: in many setups,

@tanstack/react-router

@tanstack/router-plugin

@tanstack/react-router-devtools

, and

@tanstack/react-start

should be kept on the same version line.

Query + devtools: keep major versions aligned (e.g. Query v5 with
```
@tanstack/react-query-devtools
```
).

Use

scripts/tanstack-audit.mjs

to detect mismatches.

部分TanStack包家族设计为协同更新。

Router + Start：在许多配置中，

@tanstack/react-router

、

@tanstack/router-plugin

、

@tanstack/react-router-devtools

和

@tanstack/react-start

应保持在同一版本线上。

Query + 开发工具：保持主版本对齐（例如Query v5与
```
@tanstack/react-query-devtools
```
配合使用）。

使用

scripts/tanstack-audit.mjs

检测版本不匹配问题。

SSR and data correctness first

优先保证SSR与数据正确性

If using TanStack Start, treat server-only code as server-only (keys, secrets, DB credentials).
For Query, ensure prefetch + dehydrate/hydrate is correct, and avoid double-fetching.
For Router, prefer loader/action patterns for route-coupled data.

若使用TanStack Start，确保仅服务端代码（密钥、机密信息、数据库凭证）仅在服务端运行。
对于Query，确保预取 + 脱水/水合流程正确，避免重复请求。
对于Router，优先使用loader/action模式处理与路由绑定的数据。

Performance defaults

性能默认配置

Tables and virtual lists can become performance traps.
Enforce stable references (memoize columns/data), use virtualization where appropriate, and avoid unnecessary rerenders.

表格和虚拟化列表可能成为性能瓶颈。
确保引用稳定（缓存列/数据），在合适的场景下使用虚拟化，避免不必要的重渲染。

Devtools are part of the feature set

开发工具是功能的一部分

Prefer the TanStack Devtools unified panel when possible.
Otherwise use dedicated devtools (e.g. Query devtools component) and ensure dev-only loading.

尽可能优先使用TanStack Devtools统一面板。
否则，使用专用开发工具（例如Query开发工具组件）并确保仅在开发环境加载。

Common integration recipes

常见集成方案

Start + Router + Query baseline

Start + Router + Query 基础配置

Use Router’s route loaders for route-coupled data needs.
Use Query for cached async state and background refetching.
In Start, consider preloading/prefetching queries in loaders and then dehydrating for the client.

使用Router的路由loader处理与路由绑定的数据需求。
使用Query处理缓存的异步状态和后台重新请求。
在Start中，考虑在loader中预加载/预取查询，然后脱水后提供给客户端。

Store + Router context

Store + Router 上下文

Use
```
@tanstack/react-store
```
for small, app-wide reactive state (auth state, UI preferences, feature flags).
Prefer Router route context for values that are truly navigation-scoped.

使用
```
@tanstack/react-store
```
管理小型、全局响应式状态（认证状态、UI偏好、功能开关）。
对于真正属于导航范围的值，优先使用Router的路由上下文。

DB + Query

Use DB for local-first reads/writes and live queries.
Sync to server via the collection’s mutation hooks/handlers.
Consider DB-backed collections that plug into Query for cache coherence.

使用DB处理本地优先的读写和实时查询。
通过集合的mutation钩子/处理器同步到服务端。
考虑将DB支持的集合与Query集成以保证缓存一致性。

Table + Query + Virtual

Use Query to fetch server-side paginated/sorted data.
Use Table for column/sorting/filtering state.
Use Virtual for rendering only visible rows (especially > 200 rows).

使用Query获取服务端分页/排序的数据。
使用Table处理列/排序/过滤状态。
使用Virtual仅渲染可见行（尤其是当行数>200时）。

Pacer + Query for debounced/throttled fetching

Pacer + Query 实现防抖/节流请求

Use Pacer when you need stable, testable debouncing/throttling primitives.
Typical examples: typeahead search, scroll/resize handlers, rate-limited mutation bursts.

当你需要稳定、可测试的防抖/节流原语时，使用Pacer。
典型场景：联想搜索、滚动/ resize 事件处理、速率限制的批量mutation。

Form + Query

Use Form for local form state.
Use Query mutations for server writes (or Start server functions).
Keep server validation canonical; client validation is UX.

使用Form处理本地表单状态。
使用Query的mutation处理服务端写入（或Start的服务端函数）。
以服务端验证为权威；客户端验证仅用于提升用户体验。

Form + Start/Router

Prefer Start server functions or Router actions.
Keep secrets on the server.
Return structured errors that map cleanly to field errors.

优先使用Start的服务端函数或Router的action。
机密信息保留在服务端。
返回结构化错误，使其能清晰映射到字段错误。

AI + Start

Keep provider keys on the server.
Stream responses (SSE) to clients.
Use tool definitions with schema validation.

供应商密钥保留在服务端。
通过SSE向客户端流式传输响应。
使用带 schema 验证的工具定义。

Devtools (unified)

Devtools（统一面板）

Use
```
@tanstack/react-devtools
```
+ plugin packages when available.
Keep devtools dev-only unless you explicitly need production debugging.

当可用时，使用
```
@tanstack/react-devtools
```
+ 插件包。
除非明确需要生产环境调试，否则仅在开发环境加载开发工具。

What “done” looks like

完成标准

When implementing TanStack features, consider the work complete only when:

✅ Dependencies are correct and versions are aligned
✅ TypeScript types are clean (no
```
any
```
escapes unless justified)
✅ SSR/hydration path is correct (no double fetch, no hydration warnings)
✅ Devtools integration exists (dev-only) for the relevant libs
✅ Performance hazards are addressed (virtualization where needed)
✅ There is a small, realistic example route/component proving the feature

当实现TanStack功能时，只有满足以下所有条件才算完成：

✅ 依赖正确且版本对齐
✅ TypeScript类型清晰（除非有充分理由，否则避免使用
```
any
```
类型）
✅ SSR/水合流程正确（无重复请求、无水合警告）
✅ 相关库已集成开发工具（仅在开发环境）
✅ 已解决性能隐患（必要时使用虚拟化）
✅ 存在一个小型、真实的示例路由/组件以验证功能

Troubleshooting checklist

故障排查清单

When something is broken, check in this order:

Versions: run
```
scripts/tanstack-audit.mjs
```
and fix mismatches.
Devtools: if available, use them to inspect Router/Query/Form/Pacer/AI state.
SSR/hydration: confirm server and client render match; verify Query hydration and Router loaders.
Duped packages: ensure there is only one installed copy of key packages (common in monorepos).
Bundler config: ensure Router plugin/devtools integrations are in the correct place (e.g. Vite plugins order).

当出现问题时，按以下顺序排查：

版本：运行
```
scripts/tanstack-audit.mjs
```
并修复版本不匹配问题。
开发工具：如果可用，使用它们检查Router/Query/Form/Pacer/AI的状态。
SSR/水合：确认服务端和客户端渲染结果一致；验证Query的水合和Router的loader。
重复包：确保关键包仅安装了一个副本（单体仓库中常见问题）。
打包工具配置：确保Router插件/开发工具集成配置在正确位置（例如Vite插件的顺序）。

What this skill does not do

本技能不包含的内容

It does not replace TanStack documentation.
It does not assume your exact framework unless you tell it (Start vs plain React).
It does not run network operations by default.

不替代TanStack官方文档。
除非你明确说明（Start vs 纯React），否则不会假设你使用的具体框架。
默认不执行网络操作。

Quick index

快速索引

Start:
```
references/tanstack-start.md
```
Router:
```
references/tanstack-router.md
```
Query:
```
references/tanstack-query.md
```
Table:
```
references/tanstack-table.md
```
DB:
```
references/tanstack-db.md
```
Store:
```
references/tanstack-store.md
```
Virtual:
```
references/tanstack-virtual.md
```
Pacer:
```
references/tanstack-pacer.md
```
Form:
```
references/tanstack-form.md
```
AI:
```
references/tanstack-ai.md
```
Devtools:
```
references/tanstack-devtools.md
```
Versioning/package map:
```
references/versioning-and-packages.md
```

Start:
```
references/tanstack-start.md
```
Router:
```
references/tanstack-router.md
```
Query:
```
references/tanstack-query.md
```
Table:
```
references/tanstack-table.md
```
DB:
```
references/tanstack-db.md
```
Store:
```
references/tanstack-store.md
```
Virtual:
```
references/tanstack-virtual.md
```
Pacer:
```
references/tanstack-pacer.md
```
Form:
```
references/tanstack-form.md
```
AI:
```
references/tanstack-ai.md
```
Devtools:
```
references/tanstack-devtools.md
```
版本控制/包映射:
```
references/versioning-and-packages.md
```