Guidelines for building production-ready Convex apps covering function organization, query patterns, validation, TypeScript usage, error handling, and the Zen of Convex design philosophy

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. The schema behind that index: Name indexes after their fields in order, and query fields in that same order. OCC and write conflicts Convex runs mutations under optimistic concurrency control. A mutation records what it read. If another mutation commits a change to any of that data first, Convex retries it. After enough retries it fails and the client sees a write conflict error. Conflicts come from three places: Two mutations writing the same document at once: counters, "last seen" fields, a shared settings doc A mutation that reads a wide range, such as .collect() on a whole table, so any change in that range conflicts with it A client calling the same mutation faster than it can commit: typing, dragging, polling Idempotent and patch first The read in complete is fine: one document, early exit. reorder never reads at all. Event records instead of counters A counter field on one document is the most common conflict source. Insert one row per event and count in a query. Once the event table gets large, move the count to the @convex dev/sharded counter or @convex dev/aggregate component instead of collecting rows. Dedup windows For heartbeats and presence, skip the write when the last one was recent. Pair it with a client side debounce: 300 to 500 ms for typing, a few seconds for heartbeats. Put hot fields such as lastSeen in their own table so those writes do not conflict with reads of the stable document. Pagination over collect .collect() on an unbounded table gets slower every day and eventually hits read limits. Paginate anything a user can grow. postValidator below is a hoisted document validator like taskValidator above. On the client, usePaginatedQuery from convex/react drives loadMore . No Date.now() in queries Queries must be deterministic so Convex can cache them and rerun them when data changes. Pass time from the client, or store a status field that a scheduled mutation updates. Mutations and actions may call Date.now() . ESLint plugin @convex dev/eslint plugin catches the old function syntax, missing arg validators, .filter() in queries, and top of the hour crons at lint time. Install it in every Convex project. Open [references/eslint setup.md](references/eslint setup.md) when you need the full rule list, the TypeScript aware config, package scripts, or a custom convex/ directory. Common mistakes Mistake Why it breaks Do instead .filter() on a table query Reads every row, then drops most Add an index, use withIndex .collect() on an unbounded table Slower every day, hits read limits, wide OCC footprint .paginate() or .take(n) Read, compute, then patch a shared doc Two clients read the same version and both write Patch directly, or split into event rows Counter field incremented per event Every increment conflicts with every other Event records or a sharded counter component Mutation without an early return Retries and double clicks apply the change twice Check state, return null if already done Sequential await on independent writes Slow, and each read widens the conflict window Promise.all Date.now() in a query Result changes every ms, cache and subscriptions break Pass now as an arg Scheduling api. Public function runs with no client auth Schedule internal. Plain Error for user messages Redacted to "Server Error" in production ConvexError Business logic inside the handler Untestable, duplicated across functions Plain helper that takes ctx Checklist [ ] Every function has args and returns [ ] Every table read uses withIndex , never .filter() [ ] Indexes are named after their fields in order [ ] Mutations return early when the doc is already in the target state [ ] Mutations patch without a prior read unless the old value is needed [ ] Independent writes run under Promise.all [ ] High frequency counts use event rows or a counter component [ ] Unbounded lists use .paginate() [ ] No Date.now() inside a query [ ] Scheduled and cron targets are internal. [ ] @convex dev/eslint plugin is installed and npm run lint passes Docs https://docs.convex.dev/llms.txt https://docs.convex.dev/understanding/best practices/ https://docs.convex.dev/database/advanced/occ https://docs.convex.dev/database/pagination https://docs.convex.dev/eslint

convex-best-practices