Convex Development

Workflow

1. Starting a project – See patterns for structure, types, validators
2. Database queries – See queries for indexes, filtering, performance
3. Actions and scheduling – See actions for external APIs, transactions
4. Realtime features – See realtime for subscriptions, optimistic updates
5. HTTP endpoints – See http for webhooks, REST, CORS
6. File handling – See file-storage for uploads, serving
7. Background jobs – See cron for scheduled functions
8. Schema changes – See migrations for data evolution
9. AI integration – See agents for LLM chat, RAG, tool calling
10. Security – See security for auth, ConvexError, ESLint, access control
11. Code review – See review for production readiness checklist
12. Components – See components for reusable Convex packages

convex-helpers (npm package)

13. Custom functions & Zod – See helpers-functions for middleware, auth wrappers, Zod validation
14. Data helpers – See helpers-data for relationships, CRUD, triggers, filter, pagination
15. Security helpers – See helpers-security for RLS, rate limiting, sessions, CORS
16. Async helpers – See helpers-async for workpool, action retries, migrations
17. Validation helpers – See helpers-validation for validator utils, Standard Schema, codegen
18. Integration helpers – See helpers-integrations for Hono, query caching, useQuery, QueryStreams

Key Principles

• Always define args AND returns validators on every function
• Use ConvexError with structured codes, not plain Error
• Use .withIndex() not .filter() for database queries
• Use internal.* (never api.*) for scheduling and ctx.run* calls
• Use "use node"; only when you need Node.js APIs
• Keep business logic in convex/model/ helpers, thin public API wrappers
• Always await promises (ctx.db.*, ctx.scheduler.*)
• Install @convex-dev/eslint-plugin for build-time validation

Rule Categories by Priority

1. Security (CRITICAL)

• security-auth-check – Always check authentication in public functions
• security-internal-functions – Use internal functions for scheduling and ctx.run calls
• security-row-level-access – Verify row-level ownership before mutations
• security-convex-error – Use ConvexError instead of plain Error
• security-rate-limiting – Implement rate limiting for public mutations
• security-table-name – Include table name in ctx.db calls

2. Validation (HIGH)

• validation-return-types – Always define return validators on functions

3. Performance (HIGH)

• performance-no-filter – Use .withIndex() instead of .filter() on queries
• performance-bounded-collect – Only use .collect() with bounded result sets
• performance-no-date-now – Don’t use Date.now() in query functions

4. Code Quality (MEDIUM)

• code-quality-await-promises – Always await async operations

How to Use

Read individual rule files for detailed explanations and code examples:

rules/security-auth-check.md
rules/performance-no-filter.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation