convex-components

Q: How do I install convex-components?

Run npx skills add https://github.com/igorwarzocha/opencode-workflows --skill convex-components in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/convex-components/ (personal) or .claude/skills/convex-components/ (project).

by igorwarzochaBackend & APIs

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

Installs: 92
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/igorwarzocha/opencode-workflows --skill convex-components

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads convex-components automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

<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>

FAQ

What does the convex-components skill do?

How do I install convex-components?

Run npx skills add https://github.com/igorwarzocha/opencode-workflows --skill convex-components in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/convex-components/ (personal) or .claude/skills/convex-components/ (project).

Which AI agents can use convex-components?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is convex-components safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains convex-components?

It is published by igorwarzocha in igorwarzocha/opencode-workflows. It has 92 recorded installs.