convex-development
Apply Convex database best practices for cost optimization, performance, security, and architecture.Use when: building Convex backends, optimizing queries, handling embeddings/vector search,reviewing Convex code, designing schemas, planning migrations, or discussing Convex architecture.Keywords: Convex, real-time database, queries, mutations, actions, indexes, pagination,vector search, embeddings, schema, migrations, ctx.auth, convex-helpers, bandwidth.
When & Why to Use This Skill
This Claude skill provides comprehensive best practices for Convex database development, focusing on cost-efficiency, performance optimization, and secure architecture. It guides developers through schema design, real-time query optimization, and the implementation of scalable backend patterns to ensure robust and maintainable applications.
Use Cases
- Optimizing database performance and reducing operational costs by implementing efficient indexing and pagination strategies.
- Designing secure and scalable backend architectures using the recommended 'convex/model/' pattern to separate business logic from API wrappers.
- Implementing advanced search capabilities, including vector search and embeddings, for AI-integrated real-time applications.
- Ensuring robust security by enforcing strict authentication patterns and protecting data access using ctx.auth and convex-helpers.
- Managing complex database migrations and schema updates using the Expand/Contract pattern to ensure zero-downtime environment transitions.
| name | convex-development |
|---|---|
| description | | |
| Use when | building Convex backends, optimizing queries, handling embeddings/vector search, |
| Keywords | Convex, real-time database, queries, mutations, actions, indexes, pagination, |
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
- ALWAYS commit
convex/_generated/- Required for type-checking, CI/CD, team productivity - Index what you query -
.withIndex()not.filter()for efficient queries - Paginate everything - Never unbounded
.collect()on user-facing queries - Trust
ctx.authonly - 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, paginationreferences/embeddings-vectors.md- Vector search patterns, co-location decisionsreferences/query-performance.md- Compound indexes, query segmentation, cachingreferences/security-access.md- Auth patterns, RLS, RBAC, convex-helpersreferences/schema-migrations.md- Expand/Contract pattern, environment managementreferences/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
useQueryfor 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.