convex-components

Convex Components

Components are sandboxed packages with their own database tables, functions, and isolated execution.

Universal Installation Pattern

All components follow the same installation pattern:

npm install @convex-dev/<component-name>

// convex/convex.config.ts
import { defineApp } from 'convex/server';
import componentName from '@convex-dev/<component-name>/convex.config';

const app = defineApp();
app.use(componentName);

// Multiple instances with different names
app.use(componentName, { name: 'instance2' });

export default app;

Run npx convex dev to generate code.

Accessing Components

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

// Default instance
const instance = new ComponentClass(components.componentName, {
  /* config */
});

// Named instance
const instance2 = new ComponentClass(components.instance2, {
  /* config */
});

Transaction Semantics

Component mutations participate in the parent transaction:

export const doWork = mutation({
  handler: async (ctx) => {
    await ctx.db.insert('myTable', { data: 'value' });
    await component.doSomething(ctx); // Same transaction

    // If mutation throws, BOTH writes roll back
  }
});

Component exceptions can be caught:

try {
  await rateLimiter.limit(ctx, 'myLimit', { throws: true });
} catch (e) {
  // Only component's writes roll back
  // Parent mutation can continue
}

Available Components

Durable Functions

• Workflow - Long-running, durable code flows with retries
• Workpool - Queue actions with parallelism limits
• Action Retrier - Retry failed actions with backoff

Backend Utilities

• Rate Limiter - Application-layer rate limiting
• Aggregate - Efficient COUNT, SUM, MAX operations
• Sharded Counter - High-throughput counting
• Presence - Real-time user presence tracking
• Action Cache - Cache expensive action results
• Migrations - Stateful online data migrations