convex-best-practices_skill

Overview

This skill provides concise, production-ready guidelines for building Convex applications. It covers function organization, query patterns, validation, TypeScript usage, error handling, and strategies to avoid write conflicts. The guidance emphasizes practical patterns that reduce bugs and improve performance in real apps.

How this skill works

The skill inspects common Convex development areas and prescribes concrete patterns: file organization by domain, validators for args and returns, index-based queries, idempotent mutations, and TypeScript typing with Id and Doc. It highlights when to use internal vs public functions and shows safe error handling with ConvexError. Examples and anti-patterns illustrate each recommendation.

When to use it

• When designing the server API surface for a Convex-powered app
• When optimizing queries and avoiding full-table filters
• When implementing mutations that must be safe under concurrency
• When enforcing end-to-end type safety with TypeScript
• When writing user-facing errors and internal-only operations

Best practices

• Organize functions by domain files (users.ts, tasks.ts) so intent is clear
• Always define validators for arguments and return values to catch drift
• Prefer withIndex and schema indexes over filter-based queries for performance
• Make mutations idempotent and patch directly where possible to reduce conflicts
• Use ConvexError for user-facing errors and internalMutation for sensitive ops

Example use cases

• CRUD endpoints for tasks with argument/return validators and index queries
• Batch ordering updates using Promise.all to perform parallel patches
• Simple idempotent 'completeTask' mutation that early-returns if already done
• Internal stats updater implemented as an internalMutation callable only from server code
• Type-safe references using Id and Doc types across client and server code