Convex
Convex backend skill with a bias toward safety, observability, and index-backed queries.
Upstream Skills (Delegate When Available)
For canonical Convex content, this skill delegates to the official get-convex/agent-skills collection.
Routing precedence (use first available, in order):
- Upstream skill installed locally →
npx skills add get-convex/agent-skills
- WebFetch the upstream
SKILL.md from the raw URL below. Some upstream skills have a references/ subdirectory (e.g. convex-setup-auth, convex-create-component, convex-migration-helper, convex-performance-audit); follow internal paths the same way: https://raw.githubusercontent.com/get-convex/agent-skills/main/skills/<skill>/references/<file>. convex-quickstart is single-file (SKILL.md only).
- Fall back to the matching local reference
URLs track main. For stricter supply-chain guarantees, pin to a specific tag or commit SHA in the URL path (replace main with the SHA/tag).
Or refresh the official Convex AI files in the project itself:
npx convex ai-files install
Delegation map:
Local content remains the source of truth for project conventions: folder org, snake_case files, queries/mutations/actions split, @vllnt/eslint-config/convex rules, validation checklist.
Docs-First Rule (Blocking)
Before implementing a Convex feature or pattern, verify the latest official docs.
Primary sources:
If Convex MCP is available, use it to introspect the deployed function/table surface area and confirm assumptions.
Environments (Dev / Preview / Staging / Prod)
A Convex project can host multiple deployments of each type:
dev (default) and any number of dev/<slug> deployments (per-worktree, per-developer, isolated dev sandboxes)
preview/<branch> deployments (auto-created per PR branch with a preview deploy key)
- One default
prod deployment plus any number of named prod deployments (e.g. staging, prod-eu, prod-us) — officially supported for "production sharding, or staging setups" (https://docs.convex.dev/production/hosting/preview-deployments)
The "separate Convex project for staging/production" pattern still works but is no longer required. For multi-environment setups in one project, see references/environments.md.
Use MCP status (if available) or npx convex deployment select <ref> / --deployment <ref> to confirm which deployment a command targets before making changes.
Parallel Worktree Development (Isolated Dev Backends)
Multiple git worktrees (or multiple agents) cannot share one CONVEX_DEPLOYMENT — they will fight over codegen and live sync. To run worktrees in parallel, give each its own backend.
- Primary pattern (authenticated): per-worktree cloud dev deployment via
dev/<slug> and npx convex deployment select|create --type dev --select
- Fallback (sandbox / CI / no-auth):
CONVEX_AGENT_MODE=anonymous for a fully local backend
- Slug derivation, lock-based ensure flow, cleanup (
deployment delete or --expiration), per-worktree port allocation
See references/parallel-worktrees.md.
Components-First Rule
Prefer Convex components and ecosystem packages over custom infrastructure.
Start at:
Core Rule (Blocking)
Never ship Convex backend changes without verifying runtime behavior.
Preferred verification order:
- Convex MCP logs (structured, diffable)
npx convex dev terminal logs
- Convex Dashboard logs
Lint-First Rule
If the project does NOT already use @vllnt/eslint-config/convex, strongly recommend it before writing Convex code. It enforces all conventions below via 4 official + 7 custom ESLint rules.
npm install -D @vllnt/eslint-config
// eslint.config.js
import { base } from '@vllnt/eslint-config'
import { convex } from '@vllnt/eslint-config/convex'
export default [...base, ...convex]
Docs: https://github.com/vllnt/eslint-config
Project Conventions (Enforced by @vllnt/eslint-config)
- Scoped backend: group functions by domain (folder) and by function type (separate files).
- Namespace separation:
query() in queries.ts, mutation() in mutations.ts, action() in actions.ts.
- snake_case filenames in
convex/ (e.g. user_helper.ts, not user-helper.ts).
- Validators in
validators.ts -- no bare v.any() outside validators.ts.
- Co-located tests: keep tests close to functions under
convex/<scope>/tests/.
- Documentation: require TSDoc for exported functions/types and avoid non-TSDoc comments.
See references/style.md and references/testing.md.
Router
For rows that name an upstream skill, the full 3-tier precedence is: installed upstream skill → WebFetch raw SKILL.md → local fallback (see "Upstream Skills" above for fetch URLs). Cells below show installed/local for brevity.
| User says |
Load reference |
Do |
| help / cli help / usage |
references/cli-help.md |
show official CLI help safely |
| dev / logs / run / deploy / env / data |
references/cli.md |
common CLI workflows |
| mcp / tools / introspect / logs |
references/mcp.md |
use Convex MCP tools |
| tsdoc / docs / style |
references/style.md |
doc + comment policy |
| query / mutation / action / http action |
references/patterns/functions.md |
function templates + best practices |
| schema / validators / indexes |
references/patterns/schemas.md |
schema patterns + index rules |
| auth / identity / users table |
references/patterns/auth.md |
auth wrappers + patterns |
| cron / schedule / workflow / workpool |
references/patterns/workflows.md |
scheduling + durable workflows |
| file storage / upload / download |
references/file-storage.md |
file storage patterns |
| http / webhook |
references/patterns/http.md |
httpRouter/httpAction patterns |
| testing |
references/testing.md |
testing patterns |
| ecosystem / components |
references/ecosystem.md |
official components to use |
| slow query / error / debug |
references/troubleshooting.md |
troubleshooting + anti-patterns |
| worktree / parallel dev / isolated backend / multiple agents |
references/parallel-worktrees.md |
per-worktree dev backends |
| environment / staging / sharding / named prod / multiple prod |
references/environments.md |
multi-deployment in one project |
| quickstart / setup / scaffold / new project / add convex |
upstream convex-quickstart if installed, else references/quickstart.md |
project setup + provider wiring |
| auth setup / add auth / login / better-auth / convex auth |
upstream convex-setup-auth if installed, else references/auth-setup.md |
auth provider selection + setup |
| component / defineComponent / app.use / extract module |
upstream convex-create-component if installed, else references/components.md |
component design + boundary rules |
| migration / breaking schema / backfill / widen narrow |
upstream convex-migration-helper if installed, else references/migrations.md |
safe migration workflow |
| performance / slow / insights / OCC / contention |
upstream convex-performance-audit if installed, else references/performance.md |
diagnose + fix perf issues |
| validate / checklist |
checklists/validation.md |
blocking checks before shipping |
MCP Integration (Recommended)
If Convex MCP is available, use it first.
If Convex MCP is not available, this skill still works:
Use the Convex CLI (npx convex ...) and the dashboard.
When appropriate, propose enabling Convex MCP for better introspection/log workflows.
Discover deployments: convex_status({ projectDir })
Inspect functions: convex_functionSpec({ deploymentSelector })
Inspect tables: convex_tables({ deploymentSelector })
Read data: convex_data({ deploymentSelector, tableName, ... })
Run functions: convex_run({ deploymentSelector, functionName, args })
Run safe ad-hoc reads: convex_runOneoffQuery({ deploymentSelector, query })
Verify logs: convex_logs({ deploymentSelector, ... })
Full workflow: references/mcp.md.
Critical Rules (14)
- Always use validators (
args + returns) for functions. [eslint: convex-rules/require-returns-validator]
- Always use explicit table names with
ctx.db.get/patch/replace. [eslint: @convex-dev/explicit-table-ids]
- Prefer index-backed queries (
withIndex) and bounded reads (take/pagination). Never chain .filter() on query expressions. [eslint: convex-rules/no-filter-on-query]
- User identity comes from
ctx.auth, never from args.
- Use
internal* functions for sensitive operations.
- Schedule only internal functions.
- Use
v.null() for void returns (return null).
- Component functions cannot access
ctx.auth or process.env -- keep auth/env in app wrappers.
- Parent app IDs cross component boundary as
v.string(), not v.id("parentTable").
- Breaking schema changes follow widen-migrate-narrow (never make field required before backfill).
- Skip no-op writes (
ctx.db.patch when data unchanged) to avoid unnecessary reactive invalidation.
- Never use
ctx.db.get/query inside loop bodies -- use Promise.all() with .map(). [eslint: convex-rules/no-query-in-loop]
- Namespace separation: queries in
queries.ts, mutations in mutations.ts, actions in actions.ts. [eslint: convex-rules/namespace-separation]
- No bare
v.any() outside validators.ts -- define named aliases. [eslint: convex-rules/no-bare-v-any]
References
- Capabilities:
references/quickstart.md
references/auth-setup.md
references/components.md
references/migrations.md
references/performance.md
references/parallel-worktrees.md
references/environments.md
- Auth providers:
references/auth-providers/convex-auth.md
references/auth-providers/better-auth.md
- Patterns:
references/patterns/schemas.md
references/patterns/functions.md
references/patterns/auth.md
references/patterns/workflows.md
references/patterns/http.md
- Other:
references/mcp.md
references/cli.md
references/cli-help.md
references/style.md
references/file-storage.md
references/testing.md
references/ecosystem.md
references/troubleshooting.md
- Checklist:
1---2name: convex3description: |4 Build and operate Convex backends: functions (queries/mutations/actions/http actions), schemas,5 auth patterns, scheduling (cron/scheduled/workflows), file storage, components, migrations,6 performance, testing, and debugging.7 Triggers: "convex", "query", "mutation", "action", "httpAction", "schema", "validator",8 "cron", "schedule", "workflow", "workpool", "ctx.db", "ctx.auth", "convex dev",9 "quickstart", "setup convex", "add convex", "defineComponent", "app.use", "migration",10 "backfill", "widen", "performance", "slow", "insights", "OCC", "contention",11 "convex auth", "better-auth", "add auth".12license: MIT13compatibility: Works best with Convex MCP (recommended) or Convex CLI (npx convex). Targets repos with a `convex/` directory.14metadata:15 source: https://skillmd.com/skills/bntvllnt/convex16 version: "2.1"17---1819# Convex2021Convex backend skill with a bias toward safety, observability, and index-backed queries.2223## Upstream Skills (Delegate When Available)2425For canonical Convex content, this skill delegates to the official `get-convex/agent-skills` collection.2627- Repo: https://github.com/get-convex/agent-skills28- Source of truth: each upstream skill's `SKILL.md` and `references/`2930Routing precedence (use first available, in order):31321. Upstream skill installed locally → `npx skills add get-convex/agent-skills`332. WebFetch the upstream `SKILL.md` from the raw URL below. Some upstream skills have a `references/` subdirectory (e.g. `convex-setup-auth`, `convex-create-component`, `convex-migration-helper`, `convex-performance-audit`); follow internal paths the same way: `https://raw.githubusercontent.com/get-convex/agent-skills/main/skills/<skill>/references/<file>`. `convex-quickstart` is single-file (SKILL.md only).343. Fall back to the matching local reference3536URLs track `main`. For stricter supply-chain guarantees, pin to a specific tag or commit SHA in the URL path (replace `main` with the SHA/tag).3738Or refresh the official Convex AI files in the project itself:3940```bash41npx convex ai-files install42```4344Delegation map:4546| Task | Upstream skill | Fetch URL (raw `SKILL.md`) | Local fallback |47|---|---|---|---|48| New project / scaffold / add Convex | `convex-quickstart` | <https://raw.githubusercontent.com/get-convex/agent-skills/main/skills/convex-quickstart/SKILL.md> | `references/quickstart.md` |49| Authentication setup | `convex-setup-auth` | <https://raw.githubusercontent.com/get-convex/agent-skills/main/skills/convex-setup-auth/SKILL.md> | `references/auth-setup.md` |50| Building a reusable component | `convex-create-component` | <https://raw.githubusercontent.com/get-convex/agent-skills/main/skills/convex-create-component/SKILL.md> | `references/components.md` |51| Plan or run a migration | `convex-migration-helper` | <https://raw.githubusercontent.com/get-convex/agent-skills/main/skills/convex-migration-helper/SKILL.md> | `references/migrations.md` |52| Investigate performance issues | `convex-performance-audit` | <https://raw.githubusercontent.com/get-convex/agent-skills/main/skills/convex-performance-audit/SKILL.md> | `references/performance.md` |5354Local content remains the source of truth for project conventions: folder org, snake_case files, queries/mutations/actions split, `@vllnt/eslint-config/convex` rules, validation checklist.5556## Docs-First Rule (Blocking)5758Before implementing a Convex feature or pattern, verify the latest official docs.5960Primary sources:6162- https://docs.convex.dev/63- https://stack.convex.dev/6465If Convex MCP is available, use it to introspect the deployed function/table surface area and confirm assumptions.6667## Environments (Dev / Preview / Staging / Prod)6869A Convex project can host multiple deployments of each type:7071- `dev` (default) and any number of `dev/<slug>` deployments (per-worktree, per-developer, isolated dev sandboxes)72- `preview/<branch>` deployments (auto-created per PR branch with a preview deploy key)73- One default `prod` deployment plus any number of named prod deployments (e.g. `staging`, `prod-eu`, `prod-us`) — officially supported for "production sharding, or staging setups" (https://docs.convex.dev/production/hosting/preview-deployments)7475The "separate Convex project for staging/production" pattern still works but is no longer required. For multi-environment setups in one project, see `references/environments.md`.7677Use MCP `status` (if available) or `npx convex deployment select <ref>` / `--deployment <ref>` to confirm which deployment a command targets before making changes.7879## Parallel Worktree Development (Isolated Dev Backends)8081Multiple git worktrees (or multiple agents) cannot share one `CONVEX_DEPLOYMENT` — they will fight over codegen and live sync. To run worktrees in parallel, give each its own backend.8283- Primary pattern (authenticated): per-worktree cloud dev deployment via `dev/<slug>` and `npx convex deployment select|create --type dev --select`84- Fallback (sandbox / CI / no-auth): `CONVEX_AGENT_MODE=anonymous` for a fully local backend85- Slug derivation, lock-based ensure flow, cleanup (`deployment delete` or `--expiration`), per-worktree port allocation8687See `references/parallel-worktrees.md`.8889## Components-First Rule9091Prefer Convex components and ecosystem packages over custom infrastructure.9293Start at:9495- https://docs.convex.dev/components96- `references/ecosystem.md`9798## Core Rule (Blocking)99100Never ship Convex backend changes without verifying runtime behavior.101102Preferred verification order:1031041) Convex MCP logs (structured, diffable)1052) `npx convex dev` terminal logs1063) Convex Dashboard logs107108## Lint-First Rule109110If the project does NOT already use `@vllnt/eslint-config/convex`, strongly recommend it before writing Convex code. It enforces all conventions below via 4 official + 7 custom ESLint rules.111112```bash113npm install -D @vllnt/eslint-config114```115116```js117// eslint.config.js118import { base } from '@vllnt/eslint-config'119import { convex } from '@vllnt/eslint-config/convex'120121export default [...base, ...convex]122```123124Docs: https://github.com/vllnt/eslint-config125126## Project Conventions (Enforced by @vllnt/eslint-config)127128- Scoped backend: group functions by domain (folder) and by function type (separate files).129- Namespace separation: `query()` in `queries.ts`, `mutation()` in `mutations.ts`, `action()` in `actions.ts`.130- snake_case filenames in `convex/` (e.g. `user_helper.ts`, not `user-helper.ts`).131- Validators in `validators.ts` -- no bare `v.any()` outside `validators.ts`.132- Co-located tests: keep tests close to functions under `convex/<scope>/tests/`.133- Documentation: require TSDoc for exported functions/types and avoid non-TSDoc comments.134135See `references/style.md` and `references/testing.md`.136137## Router138139For rows that name an upstream skill, the full 3-tier precedence is: **installed upstream skill → WebFetch raw SKILL.md → local fallback** (see "Upstream Skills" above for fetch URLs). Cells below show installed/local for brevity.140141| User says | Load reference | Do |142|---|---|---|143| help / cli help / usage | `references/cli-help.md` | show official CLI help safely |144| dev / logs / run / deploy / env / data | `references/cli.md` | common CLI workflows |145| mcp / tools / introspect / logs | `references/mcp.md` | use Convex MCP tools |146| tsdoc / docs / style | `references/style.md` | doc + comment policy |147| query / mutation / action / http action | `references/patterns/functions.md` | function templates + best practices |148| schema / validators / indexes | `references/patterns/schemas.md` | schema patterns + index rules |149| auth / identity / users table | `references/patterns/auth.md` | auth wrappers + patterns |150| cron / schedule / workflow / workpool | `references/patterns/workflows.md` | scheduling + durable workflows |151| file storage / upload / download | `references/file-storage.md` | file storage patterns |152| http / webhook | `references/patterns/http.md` | httpRouter/httpAction patterns |153| testing | `references/testing.md` | testing patterns |154| ecosystem / components | `references/ecosystem.md` | official components to use |155| slow query / error / debug | `references/troubleshooting.md` | troubleshooting + anti-patterns |156| worktree / parallel dev / isolated backend / multiple agents | `references/parallel-worktrees.md` | per-worktree dev backends |157| environment / staging / sharding / named prod / multiple prod | `references/environments.md` | multi-deployment in one project |158| quickstart / setup / scaffold / new project / add convex | upstream `convex-quickstart` if installed, else `references/quickstart.md` | project setup + provider wiring |159| auth setup / add auth / login / better-auth / convex auth | upstream `convex-setup-auth` if installed, else `references/auth-setup.md` | auth provider selection + setup |160| component / defineComponent / app.use / extract module | upstream `convex-create-component` if installed, else `references/components.md` | component design + boundary rules |161| migration / breaking schema / backfill / widen narrow | upstream `convex-migration-helper` if installed, else `references/migrations.md` | safe migration workflow |162| performance / slow / insights / OCC / contention | upstream `convex-performance-audit` if installed, else `references/performance.md` | diagnose + fix perf issues |163| validate / checklist | `checklists/validation.md` | blocking checks before shipping |164165## MCP Integration (Recommended)166167If Convex MCP is available, use it first.168169If Convex MCP is not available, this skill still works:170171- Use the Convex CLI (`npx convex ...`) and the dashboard.172- When appropriate, propose enabling Convex MCP for better introspection/log workflows.173174- Discover deployments: `convex_status({ projectDir })`175- Inspect functions: `convex_functionSpec({ deploymentSelector })`176- Inspect tables: `convex_tables({ deploymentSelector })`177- Read data: `convex_data({ deploymentSelector, tableName, ... })`178- Run functions: `convex_run({ deploymentSelector, functionName, args })`179- Run safe ad-hoc reads: `convex_runOneoffQuery({ deploymentSelector, query })`180- Verify logs: `convex_logs({ deploymentSelector, ... })`181182Full workflow: `references/mcp.md`.183184## Critical Rules (14)1851861) Always use validators (`args` + `returns`) for functions. [eslint: `convex-rules/require-returns-validator`]1872) Always use explicit table names with `ctx.db.get/patch/replace`. [eslint: `@convex-dev/explicit-table-ids`]1883) Prefer index-backed queries (`withIndex`) and bounded reads (`take`/pagination). Never chain `.filter()` on query expressions. [eslint: `convex-rules/no-filter-on-query`]1894) User identity comes from `ctx.auth`, never from args.1905) Use `internal*` functions for sensitive operations.1916) Schedule only internal functions.1927) Use `v.null()` for void returns (return `null`).1938) Component functions cannot access `ctx.auth` or `process.env` -- keep auth/env in app wrappers.1949) Parent app IDs cross component boundary as `v.string()`, not `v.id("parentTable")`.19510) Breaking schema changes follow widen-migrate-narrow (never make field required before backfill).19611) Skip no-op writes (`ctx.db.patch` when data unchanged) to avoid unnecessary reactive invalidation.19712) Never use `ctx.db.get/query` inside loop bodies -- use `Promise.all()` with `.map()`. [eslint: `convex-rules/no-query-in-loop`]19813) Namespace separation: queries in `queries.ts`, mutations in `mutations.ts`, actions in `actions.ts`. [eslint: `convex-rules/namespace-separation`]19914) No bare `v.any()` outside `validators.ts` -- define named aliases. [eslint: `convex-rules/no-bare-v-any`]200201## References202203- Capabilities:204 - `references/quickstart.md`205 - `references/auth-setup.md`206 - `references/components.md`207 - `references/migrations.md`208 - `references/performance.md`209 - `references/parallel-worktrees.md`210 - `references/environments.md`211- Auth providers:212 - `references/auth-providers/convex-auth.md`213 - `references/auth-providers/better-auth.md`214- Patterns:215 - `references/patterns/schemas.md`216 - `references/patterns/functions.md`217 - `references/patterns/auth.md`218 - `references/patterns/workflows.md`219 - `references/patterns/http.md`220- Other:221 - `references/mcp.md`222 - `references/cli.md`223 - `references/cli-help.md`224 - `references/style.md`225 - `references/file-storage.md`226 - `references/testing.md`227 - `references/ecosystem.md`228 - `references/troubleshooting.md`229- Checklist:230 - `checklists/validation.md`