convex-best-practices

name	convex-best-practices
description	Convex application best practices and patterns guide. This skill should be used when writing, reviewing, or refactoring Convex backend code including queries, mutations, actions, and schema definitions. Triggers on tasks involving Convex functions, database operations, authentication, or performance optimization.

Convex Best Practices

Comprehensive best practices guide for building scalable Convex applications. Contains 20+ rules across 6 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new Convex queries, mutations, or actions
• Designing database schema and indexes
• Implementing authentication and access control
• Reviewing code for performance issues
• Refactoring existing Convex functions
• Integrating Convex with React clients

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Database Performance	CRITICAL	db-
2	Security & Validation	CRITICAL	security-
3	Actions & Side Effects	HIGH	action-
4	Async Patterns	HIGH	async-
5	Code Organization	MEDIUM	org-
6	React Integration	MEDIUM	react-

Quick Reference

1. Database Performance (CRITICAL)

• db-avoid-filter - Use .withIndex instead of .filter on queries
• db-collect-limits - Only use .collect with small result sets
• db-redundant-indexes - Check for and remove redundant indexes
• db-explicit-table-ids - Always pass table name to ctx.db functions
• db-no-date-in-queries - Don't use Date.now() in queries

2. Security & Validation (CRITICAL)

• security-argument-validators - Use argument validators for all public functions
• security-access-control - Implement access control for all public functions
• security-internal-functions - Only schedule and ctx.run* internal functions

3. Actions & Side Effects (HIGH)

• action-use-sparingly - Prefer queries and mutations over actions
• action-avoid-sequential-runs - Avoid sequential ctx.runMutation/ctx.runQuery from actions
• action-run-sparingly-in-sync - Use ctx.runQuery/ctx.runMutation sparingly in queries/mutations
• action-run-action-different-runtime - Use runAction only for different runtime

4. Async Patterns (HIGH)

• async-await-all-promises - Always await all promises in Convex functions
• async-workflow-pattern - Record progress incrementally in workflows

5. Code Organization (MEDIUM)

• org-helper-functions - Use helper functions to write shared code
• org-model-directory - Structure code with a convex/model directory
• org-typescript - Use TypeScript with generated types

6. React Integration (MEDIUM)

• react-loading-states - Check for undefined to determine loading state
• react-optimistic-updates - Add optimistic updates for snappy interactions
• react-error-boundaries - Use error boundaries for Convex function errors

How to Use

Read individual rule files for detailed explanations and code examples:

rules/db-avoid-filter.md
rules/security-argument-validators.md
rules/_sections.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md