majiayu000 AgentForge — Convex
Build production-ready Convex applications using established patterns for functions, schemas, real-time data, scheduling, HTTP endpoints, migrations, and security.
Source: Adapted from waynesutton/convexskills (Apache-2.0). Always cross-check with the live docs at https://docs.convex.dev/ and https://docs.convex.dev/llms.txt before implementing.
Quick-Reference Card
| Need to… | Read reference file |
|---|---|
| Organize functions & general rules | references/best-practices.md |
| Write queries / mutations / actions | references/functions.md |
| Add real-time subs & optimistic UI | references/realtime.md |
| Define schemas, validators, indexes | references/schema-validator.md |
| Schedule recurring background work | references/cron-jobs.md |
| Create HTTP endpoints / webhooks | references/http-actions.md |
| Evolve schema & backfill data | references/migrations.md |
| Deep security review (RBAC, rate limiting) | references/security-audit.md |
| Quick security checklist | references/security-check.md |
How to use this table: Read only the reference file(s) relevant to the current task. Each file is self-contained with documentation links, code examples, best practices, and common pitfalls.
Core Principles (The Zen of Convex)
- Convex manages the hard parts — caching, real-time sync, consistency.
- Functions are the API — design them as your application's interface.
- Schema is truth — define your data model explicitly in
schema.ts. - TypeScript everywhere — leverage end-to-end type safety.
- Queries are reactive — think subscriptions, not requests.
Universal Rules
These apply to every Convex task regardless of which reference you read:
- Never run
npx convex deployunless explicitly instructed. - Never run any git commands unless explicitly instructed.
- Always define both
argsandreturnsvalidators on every function. - Use indexes (
withIndex) instead of.filter()for efficient queries. - Use
internalMutation/internalQuery/internalActionfor anything that should not be callable from the client. - Use
ConvexErrorfor user-facing errors; sanitize internal errors. - Store all secrets in environment variables; access only inside actions.
- Install and configure
@convex-dev/eslint-pluginfor build-time enforcement.
Function Types at a Glance
| Type | DB Access | External APIs | Cached / Reactive | Typical Use |
|---|---|---|---|---|
| Query | Read-only | No | Yes | Fetching data |
| Mutation | Read / Write | No | No | Modifying data |
| Action | Via runQuery/runMutation |
Yes | No | External integrations |
| HTTP Action | Via runQuery/runMutation |
Yes | No | Webhooks, REST APIs |
Linting Setup
npm i @convex-dev/eslint-plugin --save-dev
// eslint.config.js
import { defineConfig } from "eslint/config";
import convexPlugin from "@convex-dev/eslint-plugin";
export default defineConfig([
...convexPlugin.configs.recommended,
]);
Enforced rules: object syntax with handler, argument validators on all
functions, explicit table names in DB operations, no Node imports in the
Convex runtime.
Canonical Documentation Links
- Best Practices: https://docs.convex.dev/understanding/best-practices/
- Functions: https://docs.convex.dev/functions
- Schemas & Indexes: https://docs.convex.dev/database/schemas
- Realtime / React Client: https://docs.convex.dev/client/react
- Cron Jobs: https://docs.convex.dev/scheduling/cron-jobs
- HTTP Actions: https://docs.convex.dev/functions/http-actions
- Auth: https://docs.convex.dev/auth
- Production: https://docs.convex.dev/production
- Full LLM context: https://docs.convex.dev/llms.txt