TanStack 生态 2026：从表格库到全栈框架的进化之路#

1
// TanStack Start 的路由文件：app/routes/users.$userId.tsx
2
import { createFileRoute, defer } from '@tanstack/react-router'
3
import { userQueryOptions, userPostsQueryOptions } from '../queries/users'
4

5
// Route 级别的数据加载
6
export const Route = createFileRoute('/users/$userId')({
7
  // 立即加载的数据（阻塞页面渲染）
8
  loader: async ({ context, params }) => {
9
    const user = await context.queryClient.ensureQueryData(
10
      userQueryOptions(params.userId)
11
    )
12
    return { user }
13
  },
14
  // 延迟加载的数据（不阻塞页面渲染）
15
  deferred: async ({ context, params }) => {
16
    const postsPromise = context.queryClient.ensureQueryData(
17
      userPostsQueryOptions(params.userId)
18
    )
19
    return { posts: defer(postsPromise) }
20
  },
21
  component: UserProfilePage,
22
  // 错误边界
23
  errorComponent: ({ error }) => (
24
    <div className="error-shell">
25
      <h2>加载用户信息失败</h2>
26
      <p>{error.message}</p>
27
      <RetryButton />
28
    </div>
29
  )
30
})
31

32
function UserProfilePage() {
33
  const { user } = Route.useLoaderData()
34
  // posts 是流式加载的
35
  const { posts } = Route.useDeferredData()
36

37
  return (
38
    <div>
39
      <h1>{user.name}</h1>
40
      <p>{user.bio}</p>
41
      {/* 这部分内容等 posts 加载完再展示 */}
42
      {posts ? <PostList posts={posts} /> : <SkeletonLoader />}
43
    </div>
44
  )
45
}

1
// TanStack DB 的使用示例
2
import { createDB, sql } from '@tanstack/db'
3

4
// 定义 schema
5
const db = createDB({
6
  schema: {
7
    users: {
8
      id: 'string',
9
      name: 'string',
10
      email: 'string',
11
      createdAt: 'date'
12
    },
13
    posts: {
14
      id: 'string',
15
      title: 'string',
16
      userId: 'string',
17
      published: 'boolean'
18
    }
19
  },
20
  // 数据源：可以连 REST API、GraphQL、或者 WebSocket
21
  source: {
22
    type: 'rest',
23
    baseUrl: '/api'
24
  }
25
})
26

27
// 类型安全的查询
28
async function getPublishedPosts(userId: string) {
29
  const result = await db.query(
30
    sql`SELECT p.*, u.name as author_name
31
        FROM posts p
32
        JOIN users u ON p.userId = u.id
33
        WHERE p.userId = ${userId}
34
          AND p.published = true
35
        ORDER BY p.createdAt DESC
36
        LIMIT 20`
37
  )
38
  // result 的类型是 Array<{ id: string, title: string, author_name: string, ... }>
39
  return result
40
}
41

42
// 乐观更新：先更新 UI，再同步后端
43
await db.mutate({
44
  type: 'update',
45
  table: 'posts',
46
  where: { id: postId },
47
  data: { title: newTitle }
48
}, {
49
  // 如果后端同步失败，自动回滚
50
  optimistic: true,
51
  onError: (err) => {
52
    toast.error('更新失败，已回滚')
53
  }
54
})

1
// 用 TanStack AI 实现流式对话
2
import { useChat } from '@tanstack/ai'
3

4
function ChatWidget() {
5
  const chat = useChat({
6
    model: 'gpt-5.5-turbo',
7
    systemPrompt: '你是一个友好的技术助手',
8
    // 流式输出
9
    streaming: true,
10
    // 自动管理对话历史
11
    persist: {
12
      storage: 'localStorage',
13
      maxHistory: 50
14
    }
15
  })
16

17
  return (
18
    <div className="chat-container">
19
      <div className="messages">
20
        {chat.messages.map(msg => (
21
          <div key={msg.id} className={`message ${msg.role}`}>
22
            {msg.role === 'assistant' ? (
23
              // Markdown 渲染
24
              <MarkdownRenderer content={msg.content} />
25
            ) : (
26
              <p>{msg.content}</p>
27
            )}
28
          </div>
29
        ))}
30
        {/* 流式输出中的内容实时渲染 */}
31
        {chat.streaming && chat.currentChunk && (
32
          <div className="message assistant streaming">
33
            <TypingIndicator text={chat.currentChunk} />
34
          </div>
35
        )}
36
      </div>
37
      <form onSubmit={chat.send}>
38
        <input
39
          value={chat.input}
40
          onChange={e => chat.setInput(e.target.value)}
41
          placeholder="输入消息..."
42
        />
43
        <button type="submit" disabled={chat.loading}>
44
          发送
45
        </button>
46
      </form>
47
    </div>
48
  )
49
}