1---
2name: convex-components
3description: |-
4 Use Convex Components to add isolated backend features and compose component APIs.
5 Use for installing components, calling component APIs, authoring components, and
6 handling component-specific constraints (Id types, env vars, pagination, auth).
7 Use proactively when users mention components, workpool, workflow, agent component,
8 or reusable backend modules.
9
10 Examples:
11 - user: "Install the Agent component" → add convex.config.ts + use() + components API
12 - user: "Call component functions" → ctx.runQuery(components.foo.bar, args)
13 - user: "Build a component" → defineComponent, schema, _generated, packaging
14 - user: "Expose component API to clients" → re-export functions with auth
15metadata:
16 source: https://skillmd.com/skills/igorwarzocha/convex-components
17---
18
19<overview>
20Use Convex Components to add isolated backend features and compose component APIs.
21</overview>
22
23<reference>
24- **Components overview**: https://docs.convex.dev/components
25- **Understanding**: https://docs.convex.dev/components/understanding
26- **Using**: https://docs.convex.dev/components/using
27- **Authoring**: https://docs.convex.dev/components/authoring
28- **Directory**: https://convex.dev/components
29</reference>
30
31<context name="Component References">
32You SHOULD consult these reference files for specific component knowledge:
33- `references/agent.md` — Agent component: threads/messages, streaming, tools, context, debugging, usage tracking, and install/setup.
34- `references/rag.md` — RAG component: namespaces, add/search/generateText, filters, chunking, prompt vs tool RAG.
35- `references/workpool.md` — Workpool component: enqueue, retries, onComplete, parallelism, batching, monitoring.
36- `references/workflow.md` — Workflow component: durable steps, events, retries, status, cancel/cleanup, limits.
37</context>
38
39<rules>
40
41### Mental Model
42- Components are isolated mini backends with their own schema, tables, file storage, and functions.
43- Components MUST NOT access app tables/functions/env unless passed explicitly.
44- Calls into components are transactional with the caller, but component mutations are sub-transactions.
45
46### Installing Components
47- Install package: `npm i @convex-dev/<component>`.
48- Add `convex/convex.config.ts`:
49 - `import { defineApp } from "convex/server";`
50 - `app.use(component)`; use `app.use(component, { name: "custom" })` for multiple instances.
51- You MUST run `npx convex dev` to generate component code.
52- Access via `components.<name>` in `convex/_generated/api`.
53
54### Calling Component APIs
55- Use `ctx.runQuery/Mutation/Action` with `components.<name>.<fn>`.
56- Public component functions MUST NOT be called directly from clients (they are internal references).
57- Queries remain reactive; mutations are transactional.
58
59### Transaction Semantics
60- Top-level mutation commits all writes across components together.
61- If a component mutation throws, only its writes are rolled back; the caller MAY catch and continue.
62
63### Component API Differences
64- `components.<name>` exposes ONLY public component functions.
65- `Id` types cross boundaries as `string`; You MUST NOT use `v.id("table")` for external tables.
66- Each component has its own `_generated` directory; You MUST use the app's `components` references.
67
68### Environment Variables
69- Components MUST NOT access `process.env` directly.
70- You MUST pass env values as arguments from the app, or store config in a component table.
71
72### HTTP Actions
73- Components MUST NOT expose routes directly; app MUST mount handlers in `convex/http.ts`.
74
75### Auth in Components
76- `ctx.auth` is NOT available inside component functions.
77- You MUST authenticate in the app and pass identifiers (userId) to component functions.
78
79### Pagination
80- Built-in `.paginate()` is NOT supported inside components.
81- You SHOULD use `convex-helpers` paginator and `usePaginatedQuery` from convex-helpers if needed.
82
83### Authoring Components
84- Component folder MUST include `convex.config.ts`, `schema.ts`, functions, and `_generated`.
85- `defineComponent("name")` defines component; use `component.use(...)` for child components.
86- Local components MAY live in `convex/components/` or any folder.
87- NPM components SHOULD export:
88 - `@pkg/convex.config.js`
89 - `@pkg/_generated/component.js`
90 - `@pkg/test` helpers
91
92### Function Handles
93- You SHOULD use `createFunctionHandle(api.foo.bar)` to pass callbacks across boundaries.
94- Handles are strings; use `v.string()` validators and cast back to `FunctionHandle`.
95
96### Testing Components
97- You SHOULD register component with `convex-test` using component schema/modules or provided test helpers.
98- For component packages, You SHOULD use `@pkg/test` register helper.
99
100### Best Practices
101- You MUST always validate args/returns on public component functions.
102- You SHOULD prefer app-level wrappers to add auth/rate limiting when re-exporting component APIs.
103- You SHOULD use a single-row globals/config table for static configuration.
104
105</rules>