convex-tanstack

Convex + TanStack Start

概述

本技能为使用 Convex（响应式后端即服务）与 TanStack Start（全栈 React 元框架）构建响应式、实时全栈应用提供指导。该技术栈提供实时更新的查询、端到端类型安全开发、SSR 支持以及自动缓存失效。

何时使用本技能

• 实现 Convex 查询、变更或操作
• 设置或排查 Better Auth 身份验证问题
• 配置 TanStack Router 路由和加载器
• 编写 schema 定义和索引
• 实现数据获取模式（useQuery、useSuspenseQuery）
• 使用文件存储、调度或 cron 任务
• 使用 @convex-dev/agent 构建 AI Agent
• 调试 SSR 或水合问题

快速参考

常用导入

// Data fetching (always use cached version)
import { useQuery } from 'convex-helpers/react/cache'
import { useMutation, useAction } from 'convex/react'

// SSR with React Query
import { useSuspenseQuery } from '@tanstack/react-query'
import { convexQuery } from '@convex-dev/react-query'

// API and types
import { api } from '~/convex/_generated/api'
import type { Id, Doc } from '~/convex/_generated/dataModel'

// Backend functions
import { query, mutation, action } from "./_generated/server"
import { v } from "convex/values"

跳过模式

切勿条件式调用 hook。改用 "skip"：

const user = useQuery(api.users.get, userId ? { userId } : "skip")
const org = useQuery(api.orgs.get, user?.orgId ? { orgId: user.orgId } : "skip")

三种状态的查询处理

if (data === undefined) return <Skeleton />  // Loading
if (data === null) return <NotFound />       // Not found
return <Content data={data} />               // Success

函数语法（始终包含返回值校验器）

export const getUser = query({
  args: { userId: v.id("users") },
  returns: v.union(
    v.object({ _id: v.id("users"), name: v.string() }),
    v.null()
  ),
  handler: async (ctx, args) => {
    return await ctx.db.get(args.userId)
  },
})

索引最佳实践

// Schema - name includes all fields
.index("by_organizationId_status", ["organizationId", "status"])

// Query - fields in same order as index
.withIndex("by_organizationId_status", (q) =>
  q.eq("organizationId", orgId).eq("status", "published")
)

身份验证检查（后端）

import { authComponent } from "./auth"

const user = await authComponent.getAuthUser(ctx)
if (!user) throw new Error("Not authenticated")

核心原则

1. 读取使用查询 - 查询具有响应式、可缓存且一致性强的特点
2. 保持函数快速 - 在 < 100ms 内完成，处理 < 几百条记录
3. 优先使用查询/变更而非操作 - 操作仅用于外部 API 调用
4. 始终使用索引 - 切勿使用 .filter() 进行全表扫描
5. 最小化客户端状态 - 依赖 Convex 的实时同步

常见反模式

错误	正确
import { useQuery } from 'convex/react'	import { useQuery } from 'convex-helpers/react/cache'
if (id) useQuery(...)	useQuery(..., id ? {...} : "skip")
.filter(x => x.field === val)	.withIndex("by_field", q => q.eq("field", val))
使用 ctx.db 的操作	使用 ctx.runQuery/runMutation
`count

参考文件

根据任务加载相应的参考文件：

文件	使用时机
references/01-setup.md	项目设置、配置文件、环境变量
references/02-router.md	路由设置、根路由、基于文件的路由、布局
references/03-auth.md	Better Auth 设置、注册/登录/登出、受保护路由、SSR 身份验证
references/04-data-fetching.md	useQuery、useSuspenseQuery、变更、加载器、预取
references/05-backend.md	Schema、查询、变更、操作、内部函数、HTTP 端点
references/06-types.md	TypeScript 模式、校验器、类型映射
references/07-storage.md	文件上传、下载、元数据、删除
references/08-scheduling.md	scheduler.runAfter、cron 任务
references/09-agents.md	AI Agent、工具、RAG 设置
references/10-frontend.md	组件模式、加载状态、Tailwind/shadcn
references/11-permissions.md	角色层级、功能访问模式
references/12-deployment.md	开发命令、Convex CLI、Vercel 部署
references/13-quick-reference.md	导入速查表、常见模式总结

何时加载参考文件

• 开始新项目：加载 01-setup.md
• 添加身份验证：加载 03-auth.md
• 编写后端函数：加载 05-backend.md
• 实现数据获取：加载 04-data-fetching.md
• 构建 UI 组件：加载 10-frontend.md
• 需要快速语法：加载 13-quick-reference.md