convex-functions_skill

Overview

This skill provides production-ready patterns and templates for writing Convex functions: queries, mutations, actions, HTTP endpoints, internal functions, and scheduled jobs. It focuses on robust argument validation, clear error handling, and runtime considerations for external APIs and scheduling. The examples are in JavaScript and emphasize Convex best practices for safe, maintainable backend logic.

How this skill works

The skill defines typed validators for args and returns using convex/values and exports function factories (query, mutation, action, httpAction, internalMutation). Queries are read-only and cached; mutations are transactional writes; actions run external APIs and call queries/mutations via ctx.runQuery/runMutation; HTTP actions expose webhook and REST endpoints. Internal functions encapsulate sensitive logic and scheduled functions run via ctx.scheduler.runAfter.

When to use it

• Use query functions for read-only data access that benefits from caching and reactivity.
• Use mutations for any database writes, validations, and transactional updates.
• Use actions when you must call external services (payments, email, webhooks) or use Node APIs.
• Use HTTP actions to handle webhooks or custom REST endpoints for integrations.
• Use internal functions to centralize sensitive updates callable only from other Convex functions.
• Schedule reminders or deferred work with the scheduler/runAfter API.

Best practices

• Always define args and returns validators with v.* to enforce runtime types.
• Throw ConvexError for user-facing validation failures and use generic errors for internal failures.
• "use node" at the top of action files that use Node APIs or external network access.
• Keep actions free of direct DB access; call queries/mutations through ctx.runQuery/runMutation.
• Protect sensitive operations using internalMutation/internalQuery/internalAction.
• Use the scheduler for delayed or recurring work instead of external cron where possible.

Example use cases

• A cached query to list user tasks with index-based ordering and limit validation.
• A transactional mutation that creates tasks after verifying the user exists and returning task id.
• An action to send emails via an external API, returning success status and calling internal mutations.
• An HTTP webhook endpoint that verifies signatures, parses events, and triggers internal mutations.
• A scheduled reminder created by a mutation that later inserts notifications via an internal mutation.