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

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)

1. Convex manages the hard parts — caching, real-time sync, consistency.
2. Functions are the API — design them as your application's interface.
3. Schema is truth — define your data model explicitly in schema.ts.
4. TypeScript everywhere — leverage end-to-end type safety.
5. 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 deploy unless explicitly instructed.
• Never run any git commands unless explicitly instructed.
• Always define both args and returns validators on every function.
• Use indexes (withIndex) instead of .filter() for efficient queries.
• Use internalMutation / internalQuery / internalAction for anything that should not be callable from the client.
• Use ConvexError for user-facing errors; sanitize internal errors.
• Store all secrets in environment variables; access only inside actions.
• Install and configure @convex-dev/eslint-plugin for build-time enforcement.

Function Types at a Glance

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