convex-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Convex Best Practices

Convex 最佳实践

Build production-ready Convex applications by following established patterns for function organization, query optimization, validation, TypeScript usage, and error handling.

通过遵循函数组织、查询优化、验证、TypeScript使用和错误处理的既定模式，构建可用于生产环境的Convex应用。

Code Quality

代码质量

All patterns in this skill comply with @convex-dev/eslint-plugin rules. Install the linter for build-time validation:

bash

npm i @convex-dev/eslint-plugin --save-dev

See convex-eslint for configuration details.

本技能中的所有模式均符合@convex-dev/eslint-plugin规则。安装该linter以进行构建时验证：

bash

npm i @convex-dev/eslint-plugin --save-dev

查看convex-eslint了解配置详情。

Documentation Sources

文档来源

Before implementing, do not assume; fetch the latest documentation:

Primary: https://docs.convex.dev/understanding/best-practices/
Error Handling: https://docs.convex.dev/functions/error-handling
Write Conflicts: https://docs.convex.dev/error#1
For broader context: https://docs.convex.dev/llms.txt

在实现之前，不要主观臆断；请获取最新文档：

主文档：https://docs.convex.dev/understanding/best-practices/
错误处理：https://docs.convex.dev/functions/error-handling
写入冲突：https://docs.convex.dev/error#1
更多背景：https://docs.convex.dev/llms.txt

Instructions

操作指南

The Zen of Convex

Convex 的设计准则

Convex manages the hard parts - Let Convex handle caching, real-time sync, and consistency
Functions are the API - Design your functions as your application's interface
Schema is truth - Define your data model explicitly in schema.ts
TypeScript everywhere - Leverage end-to-end type safety
Queries are reactive - Think in terms of subscriptions, not requests

Convex 负责处理复杂部分 - 让Convex处理缓存、实时同步和一致性
函数即API - 将你的函数设计为应用的接口
Schema 是唯一真理 - 在schema.ts中显式定义你的数据模型
全栈使用TypeScript - 利用端到端的类型安全
查询是响应式的 - 从订阅的角度思考，而非请求

Function Organization

函数组织

Organize your Convex functions by domain:

typescript

// convex/users.ts - User-related functions
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";

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

按领域组织你的Convex函数：

typescript

// convex/users.ts - 用户相关函数
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";

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

Argument and Return Validation

参数与返回值验证

Always define validators for arguments AND return types:

typescript

export const createTask = mutation({
  args: {
    title: v.string(),
    description: v.optional(v.string()),
    priority: v.union(v.literal("low"), v.literal("medium"), v.literal("high")),
  },
  returns: v.id("tasks"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("tasks", {
      title: args.title,
      description: args.description,
      priority: args.priority,
      completed: false,
      createdAt: Date.now(),
    });
  },
});

始终为参数和返回类型定义验证器：

typescript

export const createTask = mutation({
  args: {
    title: v.string(),
    description: v.optional(v.string()),
    priority: v.union(v.literal("low"), v.literal("medium"), v.literal("high")),
  },
  returns: v.id("tasks"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("tasks", {
      title: args.title,
      description: args.description,
      priority: args.priority,
      completed: false,
      createdAt: Date.now(),
    });
  },
});

Query Patterns

查询模式

Use indexes instead of filters for efficient queries:

typescript

// Schema with index
export default defineSchema({
  tasks: defineTable({
    userId: v.id("users"),
    status: v.string(),
    createdAt: v.number(),
  })
    .index("by_user", ["userId"])
    .index("by_user_and_status", ["userId", "status"]),
});

// Query using index
export const getTasksByUser = query({
  args: { userId: v.id("users") },
  returns: v.array(
    v.object({
      _id: v.id("tasks"),
      _creationTime: v.number(),
      userId: v.id("users"),
      status: v.string(),
      createdAt: v.number(),
    }),
  ),
  handler: async (ctx, args) => {
    return await ctx.db
      .query("tasks")
      .withIndex("by_user", (q) => q.eq("userId", args.userId))
      .order("desc")
      .collect();
  },
});

使用索引而非过滤器来实现高效查询：

typescript

// 带索引的Schema
export default defineSchema({
  tasks: defineTable({
    userId: v.id("users"),
    status: v.string(),
    createdAt: v.number(),
  })
    .index("by_user", ["userId"])
    .index("by_user_and_status", ["userId", "status"]),
});

// 使用索引进行查询
export const getTasksByUser = query({
  args: { userId: v.id("users") },
  returns: v.array(
    v.object({
      _id: v.id("tasks"),
      _creationTime: v.number(),
      userId: v.id("users"),
      status: v.string(),
      createdAt: v.number(),
    }),
  ),
  handler: async (ctx, args) => {
    return await ctx.db
      .query("tasks")
      .withIndex("by_user", (q) => q.eq("userId", args.userId))
      .order("desc")
      .collect();
  },
});

Error Handling

错误处理

Use ConvexError for user-facing errors:

typescript

import { ConvexError } from "convex/values";

export const updateTask = mutation({
  args: {
    taskId: v.id("tasks"),
    title: v.string(),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    const task = await ctx.db.get("tasks", args.taskId);

    if (!task) {
      throw new ConvexError({
        code: "NOT_FOUND",
        message: "Task not found",
      });
    }

    await ctx.db.patch("tasks", args.taskId, { title: args.title });
    return null;
  },
});

使用ConvexError处理面向用户的错误：

typescript

import { ConvexError } from "convex/values";

export const updateTask = mutation({
  args: {
    taskId: v.id("tasks"),
    title: v.string(),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    const task = await ctx.db.get("tasks", args.taskId);

    if (!task) {
      throw new ConvexError({
        code: "NOT_FOUND",
        message: "Task not found",
      });
    }

    await ctx.db.patch("tasks", args.taskId, { title: args.title });
    return null;
  },
});

Avoiding Write Conflicts (Optimistic Concurrency Control)

避免写入冲突（乐观并发控制）

Convex uses OCC. Follow these patterns to minimize conflicts:

typescript

// GOOD: Make mutations idempotent
export const completeTask = mutation({
  args: { taskId: v.id("tasks") },
  returns: v.null(),
  handler: async (ctx, args) => {
    const task = await ctx.db.get("tasks", args.taskId);

    // Early return if already complete (idempotent)
    if (!task || task.status === "completed") {
      return null;
    }

    await ctx.db.patch("tasks", args.taskId, {
      status: "completed",
      completedAt: Date.now(),
    });
    return null;
  },
});

// GOOD: Patch directly without reading first when possible
export const updateNote = mutation({
  args: { id: v.id("notes"), content: v.string() },
  returns: v.null(),
  handler: async (ctx, args) => {
    // Patch directly - ctx.db.patch throws if document doesn't exist
    await ctx.db.patch("notes", args.id, { content: args.content });
    return null;
  },
});

// GOOD: Use Promise.all for parallel independent updates
export const reorderItems = mutation({
  args: { itemIds: v.array(v.id("items")) },
  returns: v.null(),
  handler: async (ctx, args) => {
    const updates = args.itemIds.map((id, index) =>
      ctx.db.patch("items", id, { order: index }),
    );
    await Promise.all(updates);
    return null;
  },
});

Convex使用乐观并发控制。遵循以下模式以最小化冲突：

typescript

// 推荐：让幂等性的变更操作
export const completeTask = mutation({
  args: { taskId: v.id("tasks") },
  returns: v.null(),
  handler: async (ctx, args) => {
    const task = await ctx.db.get("tasks", args.taskId);

    // 如果任务已完成则提前返回（幂等性）
    if (!task || task.status === "completed") {
      return null;
    }

    await ctx.db.patch("tasks", args.taskId, {
      status: "completed",
      completedAt: Date.now(),
    });
    return null;
  },
});

// 推荐：在可能的情况下直接更新而非先读取
export const updateNote = mutation({
  args: { id: v.id("notes"), content: v.string() },
  returns: v.null(),
  handler: async (ctx, args) => {
    // 直接更新 - 如果文档不存在，ctx.db.patch会抛出错误
    await ctx.db.patch("notes", args.id, { content: args.content });
    return null;
  },
});

// 推荐：使用Promise.all并行执行独立更新
export const reorderItems = mutation({
  args: { itemIds: v.array(v.id("items")) },
  returns: v.null(),
  handler: async (ctx, args) => {
    const updates = args.itemIds.map((id, index) =>
      ctx.db.patch("items", id, { order: index }),
    );
    await Promise.all(updates);
    return null;
  },
});

TypeScript Best Practices

TypeScript 最佳实践

typescript

import { Id, Doc } from "./_generated/dataModel";

// Use Id type for document references
type UserId = Id<"users">;

// Use Doc type for full documents
type User = Doc<"users">;

// Define Record types properly
const userScores: Record<Id<"users">, number> = {};

typescript

import { Id, Doc } from "./_generated/dataModel";

// 使用Id类型表示文档引用
type UserId = Id<"users">;

// 使用Doc类型表示完整文档
type User = Doc<"users">;

// 正确定义Record类型
const userScores: Record<Id<"users">, number> = {};

Internal vs Public Functions

内部函数 vs 公共函数

typescript

// Public function - exposed to clients
export const getUser = query({
  args: { userId: v.id("users") },
  returns: v.union(
    v.null(),
    v.object({
      /* ... */
    }),
  ),
  handler: async (ctx, args) => {
    // ...
  },
});

// Internal function - only callable from other Convex functions
export const _updateUserStats = internalMutation({
  args: { userId: v.id("users") },
  returns: v.null(),
  handler: async (ctx, args) => {
    // ...
  },
});

typescript

// 公共函数 - 暴露给客户端
export const getUser = query({
  args: { userId: v.id("users") },
  returns: v.union(
    v.null(),
    v.object({
      /* ... */
    }),
  ),
  handler: async (ctx, args) => {
    // ...
  },
});

// 内部函数 - 仅可从其他Convex函数调用
export const _updateUserStats = internalMutation({
  args: { userId: v.id("users") },
  returns: v.null(),
  handler: async (ctx, args) => {
    // ...
  },
});

Examples

示例

Complete CRUD Pattern

完整CRUD模式

typescript

// convex/tasks.ts
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";
import { ConvexError } from "convex/values";

const taskValidator = v.object({
  _id: v.id("tasks"),
  _creationTime: v.number(),
  title: v.string(),
  completed: v.boolean(),
  userId: v.id("users"),
});

export const list = query({
  args: { userId: v.id("users") },
  returns: v.array(taskValidator),
  handler: async (ctx, args) => {
    return await ctx.db
      .query("tasks")
      .withIndex("by_user", (q) => q.eq("userId", args.userId))
      .collect();
  },
});

export const create = mutation({
  args: {
    title: v.string(),
    userId: v.id("users"),
  },
  returns: v.id("tasks"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("tasks", {
      title: args.title,
      completed: false,
      userId: args.userId,
    });
  },
});

export const update = mutation({
  args: {
    taskId: v.id("tasks"),
    title: v.optional(v.string()),
    completed: v.optional(v.boolean()),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    const { taskId, ...updates } = args;

    // Remove undefined values
    const cleanUpdates = Object.fromEntries(
      Object.entries(updates).filter(([_, v]) => v !== undefined),
    );

    if (Object.keys(cleanUpdates).length > 0) {
      await ctx.db.patch("tasks", taskId, cleanUpdates);
    }
    return null;
  },
});

export const remove = mutation({
  args: { taskId: v.id("tasks") },
  returns: v.null(),
  handler: async (ctx, args) => {
    await ctx.db.delete("tasks", args.taskId);
    return null;
  },
});

typescript

// convex/tasks.ts
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";
import { ConvexError } from "convex/values";

const taskValidator = v.object({
  _id: v.id("tasks"),
  _creationTime: v.number(),
  title: v.string(),
  completed: v.boolean(),
  userId: v.id("users"),
});

export const list = query({
  args: { userId: v.id("users") },
  returns: v.array(taskValidator),
  handler: async (ctx, args) => {
    return await ctx.db
      .query("tasks")
      .withIndex("by_user", (q) => q.eq("userId", args.userId))
      .collect();
  },
});

export const create = mutation({
  args: {
    title: v.string(),
    userId: v.id("users"),
  },
  returns: v.id("tasks"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("tasks", {
      title: args.title,
      completed: false,
      userId: args.userId,
    });
  },
});

export const update = mutation({
  args: {
    taskId: v.id("tasks"),
    title: v.optional(v.string()),
    completed: v.optional(v.boolean()),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    const { taskId, ...updates } = args;

    // 移除undefined值
    const cleanUpdates = Object.fromEntries(
      Object.entries(updates).filter(([_, v]) => v !== undefined),
    );

    if (Object.keys(cleanUpdates).length > 0) {
      await ctx.db.patch("tasks", taskId, cleanUpdates);
    }
    return null;
  },
});

export const remove = mutation({
  args: { taskId: v.id("tasks") },
  returns: v.null(),
  handler: async (ctx, args) => {
    await ctx.db.delete("tasks", args.taskId);
    return null;
  },
});

Best Practices

最佳实践

Never run
```
npx convex deploy
```
unless explicitly instructed
Never run any git commands unless explicitly instructed
Always define return validators for functions
Use indexes for all queries that filter data
Make mutations idempotent to handle retries gracefully
Use ConvexError for user-facing error messages
Organize functions by domain (users.ts, tasks.ts, etc.)
Use internal functions for sensitive operations
Leverage TypeScript's Id and Doc types

除非明确指示，否则不要运行
```
npx convex deploy
```
除非明确指示，否则不要运行任何git命令
始终为函数定义返回值验证器
为所有过滤数据的查询使用索引
让变更操作具有幂等性，以优雅处理重试
使用ConvexError处理面向用户的错误消息
按领域组织函数（users.ts、tasks.ts等）
使用内部函数处理敏感操作
利用TypeScript的Id和Doc类型

Common Pitfalls

常见陷阱

Using filter instead of withIndex - Always define indexes and use withIndex
Missing return validators - Always specify the returns field
Non-idempotent mutations - Check current state before updating
Reading before patching unnecessarily - Patch directly when possible
Not handling null returns - Document IDs might not exist

使用filter而非withIndex - 始终定义索引并使用withIndex
缺少返回值验证器 - 始终指定returns字段
非幂等性的变更操作 - 更新前检查当前状态
不必要的先读取再更新 - 尽可能直接更新
未处理null返回值 - 文档ID可能不存在

References

参考资料

Convex Documentation: https://docs.convex.dev/
Convex LLMs.txt: https://docs.convex.dev/llms.txt
Best Practices: https://docs.convex.dev/understanding/best-practices/
Error Handling: https://docs.convex.dev/functions/error-handling
Write Conflicts: https://docs.convex.dev/error#1

Convex文档：https://docs.convex.dev/
Convex LLMs.txt：https://docs.convex.dev/llms.txt
最佳实践：https://docs.convex.dev/understanding/best-practices/
错误处理：https://docs.convex.dev/functions/error-handling
写入冲突：https://docs.convex.dev/error#1