Convex Development

Best practices for robust, secure, performant, cost-effective Convex backends.

Core Principle

Deep modules via the convex/model/ pattern. Most logic should be plain TypeScript; query/mutation wrappers should be thin.

convex/
  _generated/         # MUST commit to git!
  model/              # Business logic (testable, reusable)
  users.ts            # Public API (thin wrappers)
  schema.ts

Critical Rules

1. ALWAYS commit convex/_generated/ - Required for type-checking, CI/CD, team productivity
2. Index what you query - .withIndex() not .filter() for efficient queries
3. Compound indexes for multi-field filters - If querying userId + status, create index ["userId", "status"] to filter at index level, not post-fetch
4. Paginate everything - Never unbounded .collect() on user-facing queries
5. Trust ctx.auth only - Never user-provided auth data

Quick Reference

Need	Use
Read data reactively	query
Write to database	mutation
External APIs, vector search	action
Scheduled tasks	internalMutation / internalAction

Anti-Patterns Scanner

Run scripts/anti_patterns_scanner.py ./convex to detect common issues.

Detailed References

For comprehensive guidance, see:

• references/cost-mitigation.md - Bandwidth optimization, indexing, pagination
• references/embeddings-vectors.md - Vector search patterns, co-location decisions
• references/query-performance.md - Compound indexes, query segmentation, caching
• references/security-access.md - Auth patterns, RLS, RBAC, convex-helpers
• references/schema-migrations.md - Expand/Contract pattern, environment management
• references/architectural-patterns.md - File organization, state machines, naming

Philosophy

• Cost First: Bandwidth is often the largest cost. Index aggressively, paginate everything.
• Security First: Never trust client input. Always use ctx.auth.
• Reactivity is Power: Use useQuery for real-time updates; don't forfeit with one-off fetches.
• Type Safety End-to-End: Leverage Convex's full type chain from database to UI.