convex-components
Use Convex Components to add isolated backend features and compose component APIs. Use for installing components, calling component APIs, authoring components, and handling component-specific constraints (Id types, env vars, pagination, auth). Use proactively when users mention components, workpool, workflow, agent component, or reusable backend modules. Examples: - user: "Install the Agent component" → add convex.config.ts + use() + components API - user: "Call component functions" → ctx.runQuery(components.foo.bar, args) - user: "Build a component" → defineComponent, schema, _generated, packaging - user: "Expose component API to clients" → re-export functions with auth
How do I install this agent skill?
npx skills add https://github.com/igorwarzocha/opencode-workflows --skill convex-componentsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill facilitates integration with the Convex backend platform, providing components for AI agents, RAG, and background workflows. It exhibits a low-risk profile due to the ingestion of user-controlled text into AI agents without explicit boundary delimiters, and the use of dynamic function handles for component callbacks.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
5 files scanned · No issues
What does this agent skill do?
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); useapp.use(component, { name: "custom" })for multiple instances.
- You MUST run
npx convex devto generate component code. - Access via
components.<name>inconvex/_generated/api.
Calling Component APIs
- Use
ctx.runQuery/Mutation/Actionwithcomponents.<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.Idtypes cross boundaries asstring; You MUST NOT usev.id("table")for external tables.- Each component has its own
_generateddirectory; You MUST use the app'scomponentsreferences.
Environment Variables
- Components MUST NOT access
process.envdirectly. - 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.authis 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-helperspaginator andusePaginatedQueryfrom convex-helpers if needed.
Authoring Components
- Component folder MUST include
convex.config.ts,schema.ts, functions, and_generated. defineComponent("name")defines component; usecomponent.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/testhelpers
Function Handles
- You SHOULD use
createFunctionHandle(api.foo.bar)to pass callbacks across boundaries. - Handles are strings; use
v.string()validators and cast back toFunctionHandle.
Testing Components
- You SHOULD register component with
convex-testusing component schema/modules or provided test helpers. - For component packages, You SHOULD use
@pkg/testregister 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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/igorwarzocha/opencode-workflows/convex-components">View convex-components on skillZs</a>