convex-best-practices

Define every Convex query and mutation with an args object using validators from convex/values, such as v.string() or v.id("tasks"). Also specify a returns validator so the function's output type is checked and exposed to clients.

Define indexes in schema.ts using .index() on the table, then query with .withIndex("by_user", q => q.eq(...)) instead of .filter(). Index-based queries avoid full table scans and scale with data size.

The @convex-dev/eslint-plugin enforces four Convex rules at build time: modern function syntax, required argument validators, explicit table names in db operations, and no Node imports in the Convex runtime. Install it and extend its recommended config in eslint.config.js.

Convex uses optimistic concurrency control, so mutations conflict when they read and write data modified concurrently. Minimize conflicts by making mutations idempotent, patching documents directly without reading first, and parallelizing independent updates with Promise.all.

Use internalMutation, internalQuery, or internalAction for logic that must not be callable from clients, such as sensitive updates or scheduled jobs. Internal functions are only invocable from other Convex functions, keeping privileged operations server-side.