| name | convex-patterns |
| description | Conventions for writing Convex backend functions, designing schemas, handling auth and multi-tenancy, and managing errors. Use when: writing Convex queries, mutations, or actions, designing a Convex schema, adding indexes, setting up multi-tenant access control, handling errors in Convex, validating data on the backend, creating cron jobs, or defining HTTP endpoints.
|
Convex Patterns
Backend conventions for Convex functions, schema design, auth, and error handling. These are opinionated patterns — not generic Convex docs.
Critical rule: Always read convex/_generated/ai/guidelines.md first when it exists in a project — it overrides general Convex knowledge from training data.
The "use node" Rule
This is the #1 mistake agents make. It gets its own callout:
- Queries and mutations go in the main entity file (V8 runtime)
- Actions needing Node.js (
"use node") go in separate files with an Actions suffix
- NEVER put
"use node" in a file that exports queries or mutations
- Example:
consultants.ts (queries/mutations) + consultantActions.ts (Node.js actions)
Reference Map
| When you need to... | Read |
|---|
| Organize files, name functions, or structure CRUD exports | references/functions.md |
| Implement auth checks, multi-tenancy, or role-based access | references/auth-multitenancy.md |
| Design tables, indexes, vectors, pagination, crons, or HTTP routes | references/schema-patterns.md |
| Handle errors, validate data, or use Zod on the backend | references/errors-validation.md |
