Convex组件指南：构建可复用后端系统的组件化架构与最佳实践

components-guide by get-convex/agent-skills

546 周安装量

17 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/get-convex/agent-skills --skill components-guide

Node.js 开发系统架构

🇨🇳中文介绍

Convex 组件指南

使用组件来封装功能，构建可维护、可复用的后端系统。

什么是 Convex 组件？

组件是自包含的迷你后端，它们捆绑了：

自身的数据模式
自身的函数（查询、变更、动作）
自身的数据（隔离的表）
清晰的 API 边界

可以将它们视为： 你后端的 npm 包，或者无需复杂部署的微服务。

为何使用组件？

传统方法（单体式）

convex/
  users.ts (500 行)
  files.ts (600 行 - 上传、存储、权限、速率限制)
  payments.ts (400 行 - Stripe、webhooks、计费)
  notifications.ts (300 行)
  analytics.ts (200 行)

总计：一个庞大的代码库，所有内容混杂在一起

组件方法（封装式）

convex/
  components/
    storage/ (文件上传 - 可复用)
    billing/ (支付 - 可复用)
    notifications/ (通知 - 可复用)
    analytics/ (分析 - 可复用)
  convex.config.ts (连接组件)
  domain/ (你的实际业务逻辑)
    users.ts (50 行 - 使用组件)
    projects.ts (75 行 - 使用组件)

总计：清晰、专注、可复用

快速开始

1. 安装组件

# 从 npm 安装官方组件
npm install @convex-dev/ratelimiter

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

2. 在 convex.config.ts 中配置

import { defineApp } from "convex/server";
import ratelimiter from "@convex-dev/ratelimiter/convex.config";

export default defineApp({
  components: {
    ratelimiter,
  },
});

3. 在你的代码中使用

import { components } from "./_generated/api";

export const createPost = mutation({
  handler: async (ctx, args) => {
    // 使用组件
    await components.ratelimiter.check(ctx, {
      key: `user:${ctx.user._id}`,
      limit: 10,
      period: 60000, // 每分钟 10 次请求
    });

    return await ctx.db.insert("posts", args);
  },
});

多个组件在同一层级协同工作：

// convex.config.ts
export default defineApp({
  components: {
    // 同级组件 - 每个处理一个关注点
    auth: authComponent,
    storage: storageComponent,
    payments: paymentsComponent,
    emails: emailComponent,
    analytics: analyticsComponent,
  },
});

示例：使用同级组件的完整功能

// convex/subscriptions.ts
import { components } from "./_generated/api";

export const subscribe = mutation({
  args: { plan: v.string() },
  handler: async (ctx, args) => {
    // 1. 验证身份验证 (auth 组件)
    const user = await components.auth.getCurrentUser(ctx);

    // 2. 创建支付 (payments 组件)
    const subscription = await components.payments.createSubscription(ctx, {
      userId: user._id,
      plan: args.plan,
      amount: getPlanAmount(args.plan),
    });

    // 3. 跟踪转化 (analytics 组件)
    await components.analytics.track(ctx, {
      event: "subscription_created",
      userId: user._id,
      plan: args.plan,
    });

    // 4. 发送确认邮件 (emails 组件)
    await components.emails.send(ctx, {
      to: user.email,
      template: "subscription_welcome",
      data: { plan: args.plan },
    });

    // 5. 在主应用中存储订阅信息
    await ctx.db.insert("subscriptions", {
      userId: user._id,
      paymentId: subscription.id,
      plan: args.plan,
      status: "active",
    });

    return subscription;
  },
});

浏览组件目录：

@convex-dev/better-auth - Better Auth 集成

@convex-dev/r2 - Cloudflare R2 文件存储
@convex-dev/storage - 文件上传/下载

@convex-dev/polar - Polar 计费与订阅

@convex-dev/agent - AI 智能体工作流
@convex-dev/embeddings - 向量存储与搜索

@convex-dev/ratelimiter - 速率限制
@convex-dev/aggregate - 数据聚合
@convex-dev/action-cache - 缓存动作结果
@convex-dev/sharded-counter - 分布式计数器
@convex-dev/migrations - 模式迁移
@convex-dev/workflow - 工作流编排

创建你自己的组件

功能是自包含的
你会在多个项目中复用
希望与团队/社区分享
具有自身数据模型的复杂功能
第三方集成包装器

不好的理由：

一次性的业务逻辑
与主应用紧密耦合
简单的工具函数

mkdir -p convex/components/notifications

// convex/components/notifications/convex.config.ts
import { defineComponent } from "convex/server";

export default defineComponent("notifications");

// convex/components/notifications/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  notifications: defineTable({
    userId: v.id("users"),
    message: v.string(),
    read: v.boolean(),
    createdAt: v.number(),
  })
    .index("by_user", ["userId"])
    .index("by_user_and_read", ["userId", "read"]),
});

// convex/components/notifications/send.ts
import { mutation } from "./_generated/server";
import { v } from "convex/values";

export const send = mutation({
  args: {
    userId: v.id("users"),
    message: v.string(),
  },
  handler: async (ctx, args) => {
    await ctx.db.insert("notifications", {
      userId: args.userId,
      message: args.message,
      read: false,
      createdAt: Date.now(),
    });
  },
});

export const markRead = mutation({
  args: { notificationId: v.id("notifications") },
  handler: async (ctx, args) => {
    await ctx.db.patch(args.notificationId, { read: true });
  },
});

// convex/components/notifications/read.ts
import { query } from "./_generated/server";
import { v } from "convex/values";

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

export const unreadCount = query({
  args: { userId: v.id("users") },
  handler: async (ctx, args) => {
    const unread = await ctx.db
      .query("notifications")
      .withIndex("by_user_and_read", q =>
        q.eq("userId", args.userId).eq("read", false)
      )
      .collect();

    return unread.length;
  },
});

父级到组件（良好）

// 主应用调用组件
await components.storage.upload(ctx, file);
await components.analytics.track(ctx, event);

父级到多个同级组件（良好）

// 主应用编排多个组件
await components.auth.verify(ctx);
const file = await components.storage.upload(ctx, data);
await components.notifications.send(ctx, message);

组件接收父级数据（良好）

// 将父级表的 ID 传递给组件
await components.audit.log(ctx, {
  userId: user._id, // 来自父级的 users 表
  action: "delete",
  resourceId: task._id, // 来自父级的 tasks 表
});

// 组件将这些存储为字符串/ID
// 但不直接访问父级表

组件访问父级表（错误）

// 在组件代码内部 - 不要这样做
const user = await ctx.db.get(userId); // 错误！无法访问父级表

同级组件间通信（错误）

组件不能直接互相调用。如果你需要这种功能，它们应该放在主应用中，或者重新设计。

每个组件做好一件事：

存储组件处理文件
身份验证组件处理身份验证
不要创建包含一切的 "工具" 组件

2. 清晰的 API 接口

// 只导出需要的内容
export { upload, download, delete } from "./storage";

// 保持内部函数私有
// (不要导出辅助函数)

// 良好：将数据作为参数传递
await components.audit.log(ctx, {
  userId: user._id,
  action: "delete"
});

// 错误：组件访问父级表
// (虽然不可能，但说明了原则)

4. 为组件添加版本号

{
  "name": "@yourteam/notifications-component",
  "version": "1.0.0"
}

5. 为组件编写文档

包含 README，说明：

组件的作用
如何安装
如何使用
API 参考
示例

浏览组件目录寻找现有解决方案
通过 npm 安装组件：npm install @convex-dev/component-name
在 convex.config.ts 中配置
使用同级组件进行功能封装
为可复用功能创建你自己的组件
保持组件专注（单一职责）
独立测试组件
编写组件 API 文档
正确地为组件添加版本号

🇺🇸English

Convex Components Guide

Use components to encapsulate features and build maintainable, reusable backends.

What Are Convex Components?

Components are self-contained mini-backends that bundle:

Their own database schema
Their own functions (queries, mutations, actions)
Their own data (isolated tables)
Clear API boundaries

Think of them as: npm packages for your backend, or microservices without the deployment complexity.

Why Use Components?

Traditional Approach (Monolithic)

convex/
  users.ts (500 lines)
  files.ts (600 lines - upload, storage, permissions, rate limiting)
  payments.ts (400 lines - Stripe, webhooks, billing)
  notifications.ts (300 lines)
  analytics.ts (200 lines)

Total: One big codebase, everything mixed together

Component Approach (Encapsulated)

convex/
  components/
    storage/ (File uploads - reusable)
    billing/ (Payments - reusable)
    notifications/ (Alerts - reusable)
    analytics/ (Tracking - reusable)
  convex.config.ts (Wire components together)
  domain/ (Your actual business logic)
    users.ts (50 lines - uses components)
    projects.ts (75 lines - uses components)

Total: Clean, focused, reusable

Quick Start

1. Install a Component

# Official components from npm
npm install @convex-dev/ratelimiter

2. Configure in convex.config.ts

import { defineApp } from "convex/server";
import ratelimiter from "@convex-dev/ratelimiter/convex.config";

export default defineApp({
  components: {
    ratelimiter,
  },
});

3. Use in Your Code

import { components } from "./_generated/api";

export const createPost = mutation({
  handler: async (ctx, args) => {
    // Use the component
    await components.ratelimiter.check(ctx, {
      key: `user:${ctx.user._id}`,
      limit: 10,
      period: 60000, // 10 requests per minute
    });

    return await ctx.db.insert("posts", args);
  },
});

Sibling Components Pattern

Multiple components working together at the same level:

// convex.config.ts
export default defineApp({
  components: {
    // Sibling components - each handles one concern
    auth: authComponent,
    storage: storageComponent,
    payments: paymentsComponent,
    emails: emailComponent,
    analytics: analyticsComponent,
  },
});

Example: Complete Feature Using Siblings

// convex/subscriptions.ts
import { components } from "./_generated/api";

export const subscribe = mutation({
  args: { plan: v.string() },
  handler: async (ctx, args) => {
    // 1. Verify authentication (auth component)
    const user = await components.auth.getCurrentUser(ctx);

    // 2. Create payment (payments component)
    const subscription = await components.payments.createSubscription(ctx, {
      userId: user._id,
      plan: args.plan,
      amount: getPlanAmount(args.plan),
    });

    // 3. Track conversion (analytics component)
    await components.analytics.track(ctx, {
      event: "subscription_created",
      userId: user._id,
      plan: args.plan,
    });

    // 4. Send confirmation (emails component)
    await components.emails.send(ctx, {
      to: user.email,
      template: "subscription_welcome",
      data: { plan: args.plan },
    });

    // 5. Store subscription in main app
    await ctx.db.insert("subscriptions", {
      userId: user._id,
      paymentId: subscription.id,
      plan: args.plan,
      status: "active",
    });

    return subscription;
  },
});

Official Components

Browse Component Directory:

Authentication

@convex-dev/better-auth - Better Auth integration

Storage

@convex-dev/r2 - Cloudflare R2 file storage
@convex-dev/storage - File upload/download

Payments

@convex-dev/polar - Polar billing & subscriptions

AI

@convex-dev/agent - AI agent workflows
@convex-dev/embeddings - Vector storage & search

Backend Utilities

@convex-dev/ratelimiter - Rate limiting
@convex-dev/aggregate - Data aggregations
@convex-dev/action-cache - Cache action results
@convex-dev/sharded-counter - Distributed counters
@convex-dev/migrations - Schema migrations
@convex-dev/workflow - Workflow orchestration

Creating Your Own Component

When to Create a Component

Good reasons:

Feature is self-contained
You'll reuse it across projects
Want to share with team/community
Complex feature with its own data model
Third-party integration wrapper

Not good reasons:

One-off business logic
Tightly coupled to main app
Simple utility functions

Structure

mkdir -p convex/components/notifications



// convex/components/notifications/convex.config.ts
import { defineComponent } from "convex/server";

export default defineComponent("notifications");



// convex/components/notifications/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  notifications: defineTable({
    userId: v.id("users"),
    message: v.string(),
    read: v.boolean(),
    createdAt: v.number(),
  })
    .index("by_user", ["userId"])
    .index("by_user_and_read", ["userId", "read"]),
});



// convex/components/notifications/send.ts
import { mutation } from "./_generated/server";
import { v } from "convex/values";

export const send = mutation({
  args: {
    userId: v.id("users"),
    message: v.string(),
  },
  handler: async (ctx, args) => {
    await ctx.db.insert("notifications", {
      userId: args.userId,
      message: args.message,
      read: false,
      createdAt: Date.now(),
    });
  },
});

export const markRead = mutation({
  args: { notificationId: v.id("notifications") },
  handler: async (ctx, args) => {
    await ctx.db.patch(args.notificationId, { read: true });
  },
});



// convex/components/notifications/read.ts
import { query } from "./_generated/server";
import { v } from "convex/values";

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

export const unreadCount = query({
  args: { userId: v.id("users") },
  handler: async (ctx, args) => {
    const unread = await ctx.db
      .query("notifications")
      .withIndex("by_user_and_read", q =>
        q.eq("userId", args.userId).eq("read", false)
      )
      .collect();

    return unread.length;
  },
});

Component Communication Patterns

Parent to Component (Good)

// Main app calls component
await components.storage.upload(ctx, file);
await components.analytics.track(ctx, event);

Parent to Multiple Siblings (Good)

// Main app orchestrates multiple components
await components.auth.verify(ctx);
const file = await components.storage.upload(ctx, data);
await components.notifications.send(ctx, message);

Component Receives Parent Data (Good)

// Pass IDs from parent's tables to component
await components.audit.log(ctx, {
  userId: user._id, // From parent's users table
  action: "delete",
  resourceId: task._id, // From parent's tasks table
});

// Component stores these as strings/IDs
// but doesn't access parent tables directly

Component to Parent Tables (Bad)

// Inside component code - DON'T DO THIS
const user = await ctx.db.get(userId); // Error! Can't access parent tables

Sibling to Sibling (Bad)

Components can't call each other directly. If you need this, they should be in the main app or refactor the design.

Best Practices

1. Single Responsibility

Each component does ONE thing well:

Storage component handles files
Auth component handles authentication
Don't create "utils" component with everything

2. Clear API Surface

// Export only what's needed
export { upload, download, delete } from "./storage";

// Keep internals private
// (Don't export helper functions)

3. Minimal Coupling

// Good: Pass data as arguments
await components.audit.log(ctx, {
  userId: user._id,
  action: "delete"
});

// Bad: Component accesses parent tables
// (Not even possible, but shows the principle)

4. Version Your Components

{
  "name": "@yourteam/notifications-component",
  "version": "1.0.0"
}

5. Document Your Components

Include README with:

What the component does
How to install
How to use
API reference
Examples

Checklist

Browse Component Directory for existing solutions
Install components via npm: npm install @convex-dev/component-name
Configure in convex.config.ts
Use sibling components for feature encapsulation
Create your own components for reusable features
Keep components focused (single responsibility)
Test components in isolation
Document component APIs
Version your components properly

Weekly Installs

546

Repository

get-convex/agent-skills

GitHub Stars

First Seen

Feb 18, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode540

github-copilot540

codex540

kimi-cli539

amp539

gemini-cli539

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

106,200 周安装