convex-best-practices

Organize production-ready Convex apps using domain-based function modules, YAML-frontmatter discovery, typed argument and return validators, and ConvexError handling to ensure consistent architecture and robust safety checks across teams.

Handle errors in Convex functions by utilizing the ConvexError class to throw typed exceptions, ensuring robust error handling and safety checks are consistently applied across all public and internal query and mutation functions.

Group Convex queries and mutations into domain-based file modules across your project, using YAML-frontmatter driven discovery to maintain consistent architecture and clear separation of concerns across teams.

Yes, this approach works with existing TypeScript projects by refactoring current functions to follow domain-based organization, adding validators for arguments and returns, and implementing index-based queries without requiring new dependencies.

Argument and return validators in Convex are needed to enforce type-safety and robust safety checks at runtime, ensuring that data flowing through public and internal functions meets strict schema requirements before database access.

Avoid write conflicts in Convex production apps by following efficient query patterns with indexes, understanding internal versus public function boundaries, and applying the Zen of Convex design philosophy for reactive data access.