convex-best-practices

Structure Convex functions by domain, such as users.ts or tasks.ts, to enforce clear boundaries. This domain-driven file organization scales maintainably from small to large projects and accelerates new developer onboarding.

Require explicit return validators and use ConvexError for user-facing exceptions to handle validation robustly. Implementing idempotent mutations prevents data inconsistencies during system retries.

TypeScript integration uses strict Id and Doc types derived from schema definitions. Emphasizing typed inputs and outputs ensures end-to-end type safety throughout your Convex application.

Explicit return validators enforce consistent coding standards and guarantee runtime data shapes match expectations. This practice strengthens end-to-end type safety between Convex queries and clients.

Implement idempotent mutations in Convex to prevent duplicate side effects during automatic network retries. This practice ensures data consistency and robust error handling across your application.

Domain-driven design in Convex applies to both small and large projects. Structuring code by domain with explicit schema usage standardizes function organization and scales smoothly as your application grows.