components-guide（组件指南）

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