Convex Component Authoring

Create self-contained, reusable Convex components with proper isolation, exports, and dependency management for sharing across projects.

Documentation Sources

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

• Primary: https://docs.convex.dev/components

• Component Authoring: https://docs.convex.dev/components/authoring

• For broader context: https://docs.convex.dev/llms.txt

Instructions

What Are Convex Components?

Convex components are self-contained packages that include:

• Database tables (isolated from the main app)

• Functions (queries, mutations, actions)

• TypeScript types and validators

• Optional frontend hooks

Component Structure

my-convex-component/ ├── package.json ├── tsconfig.json ├── README.md ├── src/ │ ├── index.ts # Main exports │ ├── component.ts # Component definition │ ├── schema.ts # Component schema │ └── functions/ │ ├── queries.ts │ ├── mutations.ts │ └── actions.ts └── convex.config.ts # Component configuration

Creating a Component

1. Component Configuration

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

export default defineComponent("myComponent");

2. Component Schema

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

export default defineSchema({ // Tables are isolated to this component items: defineTable({ name: v.string(), data: v.any(), createdAt: v.number(), }).index("by_name", ["name"]),

config: defineTable({ key: v.string(), value: v.any(), }).index("by_key", ["key"]), });

3. Component Definition

// src/component.ts import { defineComponent, ComponentDefinition } from "convex/server"; import schema from "./schema"; import * as queries from "./functions/queries"; import * as mutations from "./functions/mutations";

const component = defineComponent("myComponent", { schema, functions: { ...queries, ...mutations, }, });

export default component;

4. Component Functions

// src/functions/queries.ts import { query } from "../_generated/server"; import { v } from "convex/values";

export const list = query({ args: { limit: v.optional(v.number()), }, returns: v.array(v.object({ _id: v.id("items"), name: v.string(), data: v.any(), createdAt: v.number(), })), handler: async (ctx, args) => { return await ctx.db .query("items") .order("desc") .take(args.limit ?? 10); }, });

export const get = query({ args: { name: v.string() }, returns: v.union(v.object({ _id: v.id("items"), name: v.string(), data: v.any(), }), v.null()), handler: async (ctx, args) => { return await ctx.db .query("items") .withIndex("by_name", (q) => q.eq("name", args.name)) .unique(); }, });

// src/functions/mutations.ts import { mutation } from "../_generated/server"; import { v } from "convex/values";

export const create = mutation({ args: { name: v.string(), data: v.any(), }, returns: v.id("items"), handler: async (ctx, args) => { return await ctx.db.insert("items", { name: args.name, data: args.data, createdAt: Date.now(), }); }, });

export const update = mutation({ args: { id: v.id("items"), data: v.any(), }, returns: v.null(), handler: async (ctx, args) => { await ctx.db.patch(args.id, { data: args.data }); return null; }, });

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

5. Main Exports

// src/index.ts export { default as component } from "./component"; export * from "./functions/queries"; export * from "./functions/mutations";

// Export types for consumers export type { Id } from "./_generated/dataModel";

Using a Component

// In the consuming app's convex/convex.config.ts import { defineApp } from "convex/server"; import myComponent from "my-convex-component";

const app = defineApp();

app.use(myComponent, { name: "myComponent" });

export default app;

// In the consuming app's code import { useQuery, useMutation } from "convex/react"; import { api } from "../convex/_generated/api";

function MyApp() { // Access component functions through the app's API const items = useQuery(api.myComponent.list, { limit: 10 }); const createItem = useMutation(api.myComponent.create);

return ( <div> {items?.map((item) => ( <div key={item._id}>{item.name}</div> ))} <button onClick={() => createItem({ name: "New", data: {} })}> Add Item </button> </div> ); }

Component Configuration Options

// convex/convex.config.ts import { defineApp } from "convex/server"; import myComponent from "my-convex-component";

const app = defineApp();

// Basic usage app.use(myComponent);

// With custom name app.use(myComponent, { name: "customName" });

// Multiple instances app.use(myComponent, { name: "instance1" }); app.use(myComponent, { name: "instance2" });

export default app;

Providing Component Hooks

// src/hooks.ts import { useQuery, useMutation } from "convex/react"; import { FunctionReference } from "convex/server";

// Type-safe hooks for component consumers export function useMyComponent(api: { list: FunctionReference<"query">; create: FunctionReference<"mutation">; }) { const items = useQuery(api.list, {}); const createItem = useMutation(api.create);

return { items, createItem, isLoading: items === undefined, }; }

Publishing a Component

package.json

{ "name": "my-convex-component", "version": "1.0.0", "description": "A reusable Convex component", "main": "dist/index.js", "types": "dist/index.d.ts", "files": [ "dist", "convex.config.ts" ], "scripts": { "build": "tsc", "prepublishOnly": "npm run build" }, "peerDependencies": { "convex": "^1.0.0" }, "devDependencies": { "convex": "^1.17.0", "typescript": "^5.0.0" }, "keywords": [ "convex", "component" ] }

tsconfig.json

{ "compilerOptions": { "target": "ES2020", "module": "ESNext", "moduleResolution": "bundler", "declaration": true, "outDir": "dist", "strict": true, "esModuleInterop": true, "skipLibCheck": true }, "include": ["src/**/*"], "exclude": ["node_modules", "dist"] }

Examples

Rate Limiter Component

// rate-limiter/src/schema.ts import { defineSchema, defineTable } from "convex/server"; import { v } from "convex/values";

export default defineSchema({ requests: defineTable({ key: v.string(), timestamp: v.number(), }) .index("by_key", ["key"]) .index("by_key_and_time", ["key", "timestamp"]), });

// rate-limiter/src/functions/mutations.ts import { mutation } from "../_generated/server"; import { v } from "convex/values";

export const checkLimit = mutation({ args: { key: v.string(), limit: v.number(), windowMs: v.number(), }, returns: v.object({ allowed: v.boolean(), remaining: v.number(), resetAt: v.number(), }), handler: async (ctx, args) => { const now = Date.now(); const windowStart = now - args.windowMs;

// Clean old entries
const oldEntries = await ctx.db
  .query("requests")
  .withIndex("by_key_and_time", (q) => 
    q.eq("key", args.key).lt("timestamp", windowStart)
  )
  .collect();

for (const entry of oldEntries) {
  await ctx.db.delete(entry._id);
}

// Count current window
const currentRequests = await ctx.db
  .query("requests")
  .withIndex("by_key", (q) => q.eq("key", args.key))
  .collect();

const remaining = Math.max(0, args.limit - currentRequests.length);
const allowed = remaining > 0;

if (allowed) {
  await ctx.db.insert("requests", {
    key: args.key,
    timestamp: now,
  });
}

const oldestRequest = currentRequests[0];
const resetAt = oldestRequest 
  ? oldestRequest.timestamp + args.windowMs 
  : now + args.windowMs;

return { allowed, remaining: remaining - (allowed ? 1 : 0), resetAt };

}, });

// Usage in consuming app import { useMutation } from "convex/react"; import { api } from "../convex/_generated/api";

function useRateLimitedAction() { const checkLimit = useMutation(api.rateLimiter.checkLimit);

return async (action: () => Promise<void>) => { const result = await checkLimit({ key: "user-action", limit: 10, windowMs: 60000, });

if (!result.allowed) {
  throw new Error(`Rate limited. Try again at ${new Date(result.resetAt)}`);
}

await action();

}; }

Best Practices

• Never run npx convex deploy unless explicitly instructed

• Never run any git commands unless explicitly instructed

• Keep component tables isolated (don't reference main app tables)

• Export clear TypeScript types for consumers

• Document all public functions and their arguments

• Use semantic versioning for component releases

• Include comprehensive README with examples

• Test components in isolation before publishing

Common Pitfalls

• Cross-referencing tables - Component tables should be self-contained

• Missing type exports - Export all necessary types

• Hardcoded configuration - Use component options for customization

• No versioning - Follow semantic versioning

• Poor documentation - Document all public APIs

References

• Convex Documentation: https://docs.convex.dev/

• Convex LLMs.txt: https://docs.convex.dev/llms.txt

• Components: https://docs.convex.dev/components

• Component Authoring: https://docs.convex.dev/components/authoring