Convex best practices

Convex best practices

The patterns that keep a Convex app fast and correct in production. The rule that matters most: read as little as possible before you write, and read through an index.

Rules that matter most

1. Validators on every function. args and returns, with returns: v.null() when nothing comes back.
2. Indexes, not filters. Every table read goes through withIndex against an index in convex/schema.ts.
3. Idempotent mutations. Return early when the document is already in the target state so retries are safe.
4. Patch without reading first. ctx.db.patch(id, fields) throws if the doc is missing; you rarely need the old value.
5. Promise.all for independent writes. Do not await them one at a time.
6. Schedule internal.* only. Crons and ctx.scheduler run without a client, so public targets skip auth.
7. Thin wrappers. Auth and business logic live in plain helpers that take ctx.
8. ConvexError for anything a client should read. Plain Error messages are redacted in production.

// convex/tasks.ts
import { query, mutation } from "./_generated/server";
import { v, ConvexError } from "convex/values";

const taskValidator = v.object({
  _id: v.id("tasks"),
  _creationTime: v.number(),
  userId: v.id("users"),
  title: v.string(),
  status: v.union(v.literal("open"), v.literal("done")),
});

export const listOpen = query({
  args: { userId: v.id("users") },
  returns: v.array(taskValidator),
  handler: async (ctx, args) => {
    return await ctx.db
      .query("tasks")
      .withIndex("by_user_and_status", (q) =>
        q.eq("userId", args.userId).eq("status", "open"),
      )
      .order("desc")
      .take(100);
  },