1---
2name: convex-create-component
3description:
4  Builds reusable Convex components with isolated tables and app-facing APIs.
5  Use for new components, reusable backend modules, integrations, or component
6  boundary work.
7---
8 
9# Convex Create Component
10 
11Create reusable Convex components with clear boundaries and a small app-facing
12API.
13 
14## When to Use
15 
16- Creating a new Convex component in an existing app
17- Extracting reusable backend logic into a component
18- Building a third-party integration that should own its own tables and
19  workflows
20- Packaging Convex functionality for reuse across multiple apps
21 
22## When Not to Use
23 
24- One-off business logic that belongs in the main app
25- Thin utilities that do not need Convex tables or functions
26- App-level orchestration that should stay in `convex/`
27- Cases where a normal TypeScript library is enough
28 
29## Workflow
30 
311. Ask the user what they are building and what the end goal is. If the repo
32   already makes the answer obvious, say so and confirm before proceeding.
332. Choose the shape using the decision tree below and read the matching
34   reference file.
353. Decide whether a component is justified. Prefer normal app code or a regular
36   library if the feature does not need isolated tables, backend functions, or
37   reusable persistent state.
384. Make a short plan for:
39   - what tables the component owns
40   - what public functions it exposes
41   - what data must be passed in from the app (auth, env vars, parent IDs)
42   - what stays in the app as wrappers or HTTP mounts
435. Create the component structure with `convex.config.ts`, `schema.ts`, and
44   function files.
456. Implement functions using the component's own `./_generated/server` imports,
46   not the app's generated files.
477. Wire the component into the app with `app.use(...)`. If the app does not
48   already have `convex/convex.config.ts`, create it.
498. Call the component from the app through `components.<name>` using
50   `ctx.runQuery`, `ctx.runMutation`, or `ctx.runAction`.
519. If React clients, HTTP callers, or public APIs need access, create wrapper
52   functions in the app instead of exposing component functions directly.
5310. Run `npx convex dev` and fix codegen, type, or boundary issues before
54    finishing.
55 
56## Choose the Shape
57 
58Ask the user, then pick one path:
59 
60| Goal                                              | Shape            | Reference                           |
61| ------------------------------------------------- | ---------------- | ----------------------------------- |
62| Component for this app only                       | Local            | `references/local-components.md`    |
63| Publish or share across apps                      | Packaged         | `references/packaged-components.md` |
64| User explicitly needs local + shared library code | Hybrid           | `references/hybrid-components.md`   |
65| Not sure                                          | Default to local | `references/local-components.md`    |
66 
67Read exactly one reference file before proceeding.
68 
69## Default Approach
70 
71Unless the user explicitly wants an npm package, default to a local component:
72 
73- Put it under `convex/components/<componentName>/`
74- Define it with `defineComponent(...)` in its own `convex.config.ts`
75- Install it from the app's `convex/convex.config.ts` with `app.use(...)`
76- Let `npx convex dev` generate the component's own `_generated/` files
77 
78## Component Skeleton
79 
80A minimal local component with a table and two functions, plus the app wiring.
81 
82```ts
83// convex/components/notifications/convex.config.ts
84import { defineComponent } from "convex/server";
85 
86export default defineComponent("notifications");
87```
88 
89```ts
90// convex/components/notifications/schema.ts
91import { defineSchema, defineTable } from "convex/server";
92import { v } from "convex/values";
93 
94export default defineSchema({
95  notifications: defineTable({
96    userId: v.string(),
97    message: v.string(),
98    read: v.boolean(),
99  }).index("by_user", ["userId"]),
100});
101```
102 
103```ts
104// convex/components/notifications/lib.ts
105import { v } from "convex/values";
106import { mutation, query } from "./_generated/server.js";
107 
108export const send = mutation({
109  args: { userId: v.string(), message: v.string() },
110  returns: v.id("notifications"),
111  handler: async (ctx, args) => {
112    return await ctx.db.insert("notifications", {
113      userId: args.userId,
114      message: args.message,
115      read: false,
116    });
117  },
118});
119 
120export const listUnread = query({
121  args: { userId: v.string() },
122  returns: v.array(
123    v.object({
124      _id: v.id("notifications"),
125      _creationTime: v.number(),
126      userId: v.string(),
127      message: v.string(),
128      read: v.boolean(),
129    }),
130  ),
131  handler: async (ctx, args) => {
132    return await ctx.db
133      .query("notifications")
134      .withIndex("by_user", (q) => q.eq("userId", args.userId))
135      .filter((q) => q.eq(q.field("read"), false))
136      .collect();
137  },
138});
139```
140 
141```ts
142// convex/convex.config.ts
143import { defineApp } from "convex/server";
144import notifications from "./components/notifications/convex.config.js";
145 
146const app = defineApp();
147app.use(notifications);
148 
149export default app;
150```
151 
152```ts
153// convex/notifications.ts  (app-side wrapper)
154import { v } from "convex/values";
155import { mutation, query } from "./_generated/server";
156import { components } from "./_generated/api";
157import { getAuthUserId } from "@convex-dev/auth/server";
158 
159export const sendNotification = mutation({
160  args: { message: v.string() },
161  returns: v.null(),
162  handler: async (ctx, args) => {
163    const userId = await getAuthUserId(ctx);
164    if (!userId) throw new Error("Not authenticated");
165 
166    await ctx.runMutation(components.notifications.lib.send, {
167      userId,
168      message: args.message,
169    });
170    return null;
171  },
172});
173 
174export const myUnread = query({
175  args: {},
176  handler: async (ctx) => {
177    const userId = await getAuthUserId(ctx);
178    if (!userId) throw new Error("Not authenticated");
179 
180    return await ctx.runQuery(components.notifications.lib.listUnread, {
181      userId,
182    });
183  },
184});
185```
186 
187Note the reference path shape: a function in
188`convex/components/notifications/lib.ts` is called as
189`components.notifications.lib.send` from the app.
190 
191## Critical Rules
192 
193- Keep authentication in the app, because `ctx.auth` is not available inside
194  components.
195- Keep environment access in the app, because component functions cannot read
196  `process.env`.
197- Pass parent app IDs across the boundary as strings, because `Id` types become
198  plain strings in the app-facing `ComponentApi`.
199- Do not use `v.id("parentTable")` for app-owned tables inside component args or
200  schema, because the component has no access to the app's table namespace.
201- Import `query`, `mutation`, and `action` from the component's own
202  `./_generated/server`, not the app's generated files.
203- Do not expose component functions directly to clients. Create app wrappers
204  when client access is needed, because components are internal and need
205  auth/env wiring the app provides.
206- If the component defines HTTP handlers, mount the routes in the app's
207  `convex/http.ts`, because components cannot register their own HTTP routes.
208- If the component needs pagination, use `paginator` from `convex-helpers`
209  instead of built-in `.paginate()`, because `.paginate()` does not work across
210  the component boundary.
211- Add `args` and `returns` validators to all public component functions, because
212  the component boundary requires explicit type contracts.
213 
214## Patterns
215 
216### Authentication and environment access
217 
218```ts
219// Bad: component code cannot rely on app auth or env
220const identity = await ctx.auth.getUserIdentity();
221const apiKey = process.env.OPENAI_API_KEY;
222```
223 
224```ts
225// Good: the app resolves auth and env, then passes explicit values
226const userId = await getAuthUserId(ctx);
227if (!userId) throw new Error("Not authenticated");
228 
229await ctx.runAction(components.translator.translate, {
230  userId,
231  apiKey: process.env.OPENAI_API_KEY,
232  text: args.text,
233});
234```
235 
236### Client-facing API
237 
238```ts
239// Bad: assuming a component function is directly callable by clients
240export const send = components.notifications.send;
241```
242 
243```ts
244// Good: re-export through an app mutation or query
245export const sendNotification = mutation({
246  args: { message: v.string() },
247  returns: v.null(),
248  handler: async (ctx, args) => {
249    const userId = await getAuthUserId(ctx);
250    if (!userId) throw new Error("Not authenticated");
251 
252    await ctx.runMutation(components.notifications.lib.send, {
253      userId,
254      message: args.message,
255    });
256    return null;
257  },
258});
259```
260 
261### IDs across the boundary
262 
263```ts
264// Bad: parent app table IDs are not valid component validators
265args: {
266  userId: v.id("users");
267}
268```
269 
270```ts
271// Good: treat parent-owned IDs as strings at the boundary
272args: {
273  userId: v.string();
274}
275```
276 
277### Advanced Patterns
278 
279For additional patterns including function handles for callbacks, deriving
280validators from schema, static configuration with a globals table, and
281class-based client wrappers, see `references/advanced-patterns.md`.
282 
283## Validation
284 
285Try validation in this order:
286 
2871. `npx convex codegen --component-dir convex/components/<name>`
2882. `npx convex codegen`
2893. `npx convex dev`
290 
291Important:
292 
293- Fresh repos may fail these commands until `CONVEX_DEPLOYMENT` is configured.
294- Until codegen runs, component-local `./_generated/*` imports and app-side
295  `components.<name>...` references will not typecheck.
296- If validation blocks on Convex login or deployment setup, stop and ask the
297  user for that exact step instead of guessing.
298 
299## Reference Files
300 
301Read exactly one of these after the user confirms the goal:
302 
303- `references/local-components.md`
304- `references/packaged-components.md`
305- `references/hybrid-components.md`
306 
307Official docs:
308[Authoring Components](https://docs.convex.dev/components/authoring)
309 
310## Checklist
311 
312- [ ] Asked the user what they want to build and confirmed the shape
313- [ ] Read the matching reference file
314- [ ] Confirmed a component is the right abstraction
315- [ ] Planned tables, public API, boundaries, and app wrappers
316- [ ] Component lives under `convex/components/<name>/` (or package layout if
317      publishing)
318- [ ] Component imports from its own `./_generated/server`
319- [ ] Auth, env access, and HTTP routes stay in the app
320- [ ] Parent app IDs cross the boundary as `v.string()`
321- [ ] Public functions have `args` and `returns` validators
322- [ ] Ran `npx convex dev` and fixed codegen or type issues
323