convex-backend_skill

Overview

This skill codifies Convex backend development guidelines for writing functions, schemas, queries, mutations, actions, scheduling, and file storage. It applies when authoring server-side code in a Convex project and enforces type-safe validators, index-driven queries, and standardized function syntax. Use it to ensure consistent, efficient, and secure backend patterns across projects.

How this skill works

The skill inspects tasks that involve Convex database operations, real-time subscriptions, file blobs, or serverless functions and suggests concrete implementations aligned with best practices. It checks for required validators on function arguments and returns, recommends index usage for queries, and directs use of internal vs public function registration. It also provides patterns for actions, cron scheduling, and file storage usage so implementations remain predictable and type-safe.

When to use it

• Creating new Convex functions (query, mutation, action) or updating existing ones
• Designing or changing database schemas, indexes, and validators
• Implementing real-time subscriptions and efficient data fetching
• Adding scheduled jobs, cron-like tasks, or delayed execution
• Working with file storage, blob metadata, or external API calls from actions

Best practices

• Always declare args and returns validators for every function; use v.null() for void returns
• Prefer withIndex() queries and define indexes in schema instead of client-side filters
• Use internalQuery/internalMutation/internalAction for private functions and api.* for public ones
• Keep actions free of direct ctx.db access; call runQuery/runMutation when interacting with the DB
• Annotate types when invoking functions in the same file to preserve type safety and clarity

Example use cases

• Implementing a paginated message feed using a table index and withIndex() for efficient queries
• Creating a scheduled cleanup action that runs via cron and calls internal mutations to remove stale records
• Writing a mutation with v.object() and v.id() validators to enforce correct input shapes on writes
• Building an action that stores files in blob storage and records metadata in a Convex table
• Refactoring public/private functions to use api.* for client access and internal.* for backend-only calls