convex-components Skill

<overview> Use Convex Components to add isolated backend features and compose component APIs. </overview> <reference> - **Components overview**: https://docs.convex.dev/components - **Understanding**: https://docs.convex.dev/components/understanding - **Using**: https://docs.convex.dev/components/using - **Authoring**: https://docs.convex.dev/components/authoring - **Directory**: https://convex.dev/components </reference> <context name="Component References"> You SHOULD consult these reference files for specific component knowledge: - `references/agent.md` — Agent component: threads/messages, streaming, tools, context, debugging, usage tracking, and install/setup. - `references/rag.md` — RAG component: namespaces, add/search/generateText, filters, chunking, prompt vs tool RAG. - `references/workpool.md` — Workpool component: enqueue, retries, onComplete, parallelism, batching, monitoring. - `references/workflow.md` — Workflow component: durable steps, events, retries, status, cancel/cleanup, limits. </context> <rules>

Mental Model

Components are isolated mini backends with their own schema, tables, file storage, and functions.
Components MUST NOT access app tables/functions/env unless passed explicitly.
Calls into components are transactional with the caller, but component mutations are sub-transactions.

Installing Components

Install package: npm i @convex-dev/<component>.
Add convex/convex.config.ts:
- import { defineApp } from "convex/server";
- app.use(component); use app.use(component, { name: "custom" }) for multiple instances.
You MUST run npx convex dev to generate component code.
Access via components.<name> in convex/_generated/api.

Calling Component APIs

Use ctx.runQuery/Mutation/Action with components.<name>.<fn>.
Public component functions MUST NOT be called directly from clients (they are internal references).
Queries remain reactive; mutations are transactional.

Transaction Semantics

Top-level mutation commits all writes across components together.
If a component mutation throws, only its writes are rolled back; the caller MAY catch and continue.

Component API Differences

components.<name> exposes ONLY public component functions.
Id types cross boundaries as string; You MUST NOT use v.id("table") for external tables.
Each component has its own _generated directory; You MUST use the app's components references.

Environment Variables

Components MUST NOT access process.env directly.
You MUST pass env values as arguments from the app, or store config in a component table.

HTTP Actions

Components MUST NOT expose routes directly; app MUST mount handlers in convex/http.ts.

Auth in Components

ctx.auth is NOT available inside component functions.
You MUST authenticate in the app and pass identifiers (userId) to component functions.

Pagination

Built-in .paginate() is NOT supported inside components.
You SHOULD use convex-helpers paginator and usePaginatedQuery from convex-helpers if needed.

Authoring Components

Component folder MUST include convex.config.ts, schema.ts, functions, and _generated.
defineComponent("name") defines component; use component.use(...) for child components.
Local components MAY live in convex/components/ or any folder.
NPM components SHOULD export:
- @pkg/convex.config.js
- @pkg/_generated/component.js
- @pkg/test helpers

Function Handles

You SHOULD use createFunctionHandle(api.foo.bar) to pass callbacks across boundaries.
Handles are strings; use v.string() validators and cast back to FunctionHandle.

Testing Components

You SHOULD register component with convex-test using component schema/modules or provided test helpers.
For component packages, You SHOULD use @pkg/test register helper.

Best Practices

You MUST always validate args/returns on public component functions.
You SHOULD prefer app-level wrappers to add auth/rate limiting when re-exporting component APIs.
You SHOULD use a single-row globals/config table for static configuration.

</rules>

Agent Skills: convex-components

Install this agent skill to your local

Skill Files