components-guide

name	components-guide
description	Guide to using Convex components for feature encapsulation. Learn about sibling components, creating your own, and when to use components vs monolithic code.

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;
  },
});

What this achieves:

• ✅ Each component is single-purpose
• ✅ Components are reusable across features
• ✅ Easy to swap implementations (change email provider)
• ✅ Can update components independently
• ✅ Clear separation of concerns

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;
  },
});

Use Your Component

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

export default defineApp({
  components: {
    notifications, // Your local component
  },
});

// convex/tasks.ts - main app code
import { components } from "./_generated/api";

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

    await ctx.db.patch(args.taskId, { completed: true });

    // Use your component
    await components.notifications.send(ctx, {
      userId: task.userId,
      message: `Task "${task.title}" completed!`,
    });
  },
});

Component Communication Patterns

✅ Parent → Component (Good)

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

✅ Parent → 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 → Parent Tables (Bad)

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

❌ Sibling → Sibling (Bad)

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

Real-World Examples

Multi-Tenant SaaS

// convex.config.ts
export default defineApp({
  components: {
    auth: "@convex-dev/better-auth",
    organizations: "./components/organizations",
    billing: "./components/billing",
    storage: "@convex-dev/r2",
    analytics: "./components/analytics",
    emails: "./components/emails",
  },
});

Each component:

• auth - User authentication & sessions
• organizations - Tenant isolation & permissions
• billing - Stripe integration & subscriptions
• storage - File uploads to R2
• analytics - Event tracking & metrics
• emails - Email sending via SendGrid

E-Commerce Platform

export default defineApp({
  components: {
    cart: "./components/cart",
    inventory: "./components/inventory",
    orders: "./components/orders",
    payments: "@convex-dev/polar",
    shipping: "./components/shipping",
    recommendations: "./components/recommendations",
  },
});

AI Application

export default defineApp({
  components: {
    agent: "@convex-dev/agent",
    embeddings: "./components/embeddings",
    documents: "./components/documents",
    chat: "./components/chat",
    workflow: "@convex-dev/workflow",
  },
});

Migration from Monolithic

Step 1: Identify Features

Current monolith:
- File uploads (mixed with main app)
- Rate limiting (scattered everywhere)
- Analytics (embedded in functions)

Step 2: Extract One Feature

# Create component
mkdir -p convex/components/storage

# Move storage code to component
# Update imports in main app

Step 3: Test Independently

# Component has its own tests
# No coupling to main app

Step 4: Repeat Extract other features incrementally.

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

Troubleshooting

Component not found

# Make sure component is in convex.config.ts
# Run: npx convex dev

Can't access parent tables

This is by design! Components are sandboxed.
Pass data as arguments instead.

Component conflicts

Each component has isolated tables.
Components can't see each other's data.

Learn More

• Components Documentation
• Component Directory
• Using Components
• Authoring Components
• Stack: Backend Components

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

Remember: Components are about encapsulation and reusability. When in doubt, prefer components over monolithic code!