1# Advanced Component Patterns
2 
3Additional patterns for Convex components that go beyond the basics covered in
4the main skill file.
5 
6## Function Handles for callbacks
7 
8When the app needs to pass a callback function to the component, use function
9handles. This is common for components that run app-defined logic on a schedule
10or in a workflow.
11 
12```ts
13// App side: create a handle and pass it to the component
14import { createFunctionHandle } from "convex/server";
15 
16export const startJob = mutation({
17  handler: async (ctx) => {
18    const handle = await createFunctionHandle(internal.myModule.processItem);
19    await ctx.runMutation(components.workpool.enqueue, {
20      callback: handle,
21    });
22  },
23});
24```
25 
26```ts
27// Component side: accept and invoke the handle
28import { v } from "convex/values";
29import type { FunctionHandle } from "convex/server";
30import { mutation } from "./_generated/server.js";
31 
32export const enqueue = mutation({
33  args: { callback: v.string() },
34  handler: async (ctx, args) => {
35    const handle = args.callback as FunctionHandle<"mutation">;
36    await ctx.scheduler.runAfter(0, handle, {});
37  },
38});
39```
40 
41## Deriving validators from schema
42 
43Instead of manually repeating field types in return validators, extend the
44schema validator:
45 
46```ts
47import { v } from "convex/values";
48import schema from "./schema.js";
49 
50const notificationDoc = schema.tables.notifications.validator.extend({
51  _id: v.id("notifications"),
52  _creationTime: v.number(),
53});
54 
55export const getLatest = query({
56  args: {},
57  returns: v.nullable(notificationDoc),
58  handler: async (ctx) => {
59    return await ctx.db.query("notifications").order("desc").first();
60  },
61});
62```
63 
64## Static configuration with a globals table
65 
66A common pattern for component configuration is a single-document "globals"
67table:
68 
69```ts
70// schema.ts
71export default defineSchema({
72  globals: defineTable({
73    maxRetries: v.number(),
74    webhookUrl: v.optional(v.string()),
75  }),
76  // ... other tables
77});
78```
79 
80```ts
81// lib.ts
82export const configure = mutation({
83  args: { maxRetries: v.number(), webhookUrl: v.optional(v.string()) },
84  returns: v.null(),
85  handler: async (ctx, args) => {
86    const existing = await ctx.db.query("globals").first();
87    if (existing) {
88      await ctx.db.patch(existing._id, args);
89    } else {
90      await ctx.db.insert("globals", args);
91    }
92    return null;
93  },
94});
95```
96 
97## Class-based client wrappers
98 
99For components with many functions or configuration options, a class-based
100client provides a cleaner API. This pattern is common in published components.
101 
102```ts
103// src/client/index.ts
104import type { GenericMutationCtx, GenericDataModel } from "convex/server";
105import type { ComponentApi } from "../component/_generated/component.js";
106 
107type MutationCtx = Pick<GenericMutationCtx<GenericDataModel>, "runMutation">;
108 
109export class Notifications {
110  constructor(
111    private component: ComponentApi,
112    private options?: { defaultChannel?: string },
113  ) {}
114 
115  async send(ctx: MutationCtx, args: { userId: string; message: string }) {
116    return await ctx.runMutation(this.component.lib.send, {
117      ...args,
118      channel: this.options?.defaultChannel ?? "default",
119    });
120  }
121}
122```
123 
124```ts
125// App usage
126import { Notifications } from "@convex-dev/notifications";
127import { components } from "./_generated/api";
128 
129const notifications = new Notifications(components.notifications, {
130  defaultChannel: "alerts",
131});
132 
133export const send = mutation({
134  args: { message: v.string() },
135  handler: async (ctx, args) => {
136    const userId = await getAuthUserId(ctx);
137    await notifications.send(ctx, { userId, message: args.message });
138  },
139});
140```
141