convex-best-practices

Convex Best Practices

Build production-ready Convex applications by following established patterns for function organization, query optimization, validation, TypeScript usage, and error handling.

Code Quality

All patterns in this skill comply with @convex-dev/eslint-plugin. Install it for build-time validation:

npm i @convex-dev/eslint-plugin --save-dev

// eslint.config.js
import { defineConfig } from "eslint/config";
import convexPlugin from "@convex-dev/eslint-plugin";
 
export default defineConfig([
  ...convexPlugin.configs.recommended,
]);

The plugin enforces four rules:

Docs: https://docs.convex.dev/eslint

Documentation Sources

Before implementing, do not assume; fetch the latest documentation:

• Primary: https://docs.convex.dev/understanding/best-practices/
• Error Handling: https://docs.convex.dev/functions/error-handling
• Write Conflicts: https://docs.convex.dev/error#1
• For broader context: https://docs.convex.dev/llms.txt

Instructions

The Zen of Convex

1. Convex manages the hard parts - Let Convex handle caching, real-time sync, and consistency
2. Functions are the API - Design your functions as your application's interface
3. Schema is truth - Define your data model explicitly in schema.ts
4. TypeScript everywhere - Leverage end-to-end type safety
5. Queries are reactive - Think in terms of subscriptions, not requests

Function Organization

Organize your Convex functions by domain:

// convex/users.ts - User-related functions
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";
 
export const get = query({
  args: { userId: v.id("users") },
  returns: v.union(
    v.object({
      _id: v.id

Argument and Return Validation

Always define validators for arguments AND return types:

export const createTask = mutation({
  args: {
    title: v.string(),
    description: v.optional(v.string()),
    priority: v.union(v.literal("low"), v.literal("medium"), v.literal("high")),
  },
  returns: v.

Query Patterns

Use indexes instead of filters for efficient queries:

// Schema with index
export default defineSchema({
  tasks: defineTable({
    userId: v.id("users"),
    status: v.string(),
    createdAt: v.number(),
  })
    .index("by_user", ["userId"])

Error Handling

Use ConvexError for user-facing errors:

import { ConvexError } from "convex/values";
 
export const updateTask = mutation({
  args: {
    taskId: v.id("tasks"),
    title: v.string(),
  },
  returns: v.null(),
  handler: async (ctx, args

Avoiding Write Conflicts (Optimistic Concurrency Control)

Convex uses OCC. Follow these patterns to minimize conflicts:

// GOOD: Make mutations idempotent
export const completeTask = mutation({
  args: { taskId: v.id("tasks") },
  returns: v.null(),
  handler: async (ctx, 

TypeScript Best Practices

import { Id, Doc } from "./_generated/dataModel";
 
// Use Id type for document references
type UserId = Id<"users">;
 
// Use Doc type for full documents
type User = Doc<"users">;
 
// Define Record types properly
const userScores: Record<Id<"users">, number> 

Internal vs Public Functions

// Public function - exposed to clients
export const getUser = query({
  args: { userId: v.id("users") },
  returns: v.union(
    v.null(),
    v.object({
      /* ... */
    }),
  ),
  handler: async (ctx, 

Examples

Complete CRUD Pattern

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

Best Practices

• Never run npx convex deploy unless explicitly instructed
• Never run any git commands unless explicitly instructed
• Always define return validators for functions
• Use indexes for all queries that filter data
• Make mutations idempotent to handle retries gracefully
• Use ConvexError for user-facing error messages
• Organize functions by domain (users.ts, tasks.ts, etc.)
• Use internal functions for sensitive operations
• Leverage TypeScript's Id and Doc types

Common Pitfalls

1. Using filter instead of withIndex - Always define indexes and use withIndex
2. Missing return validators - Always specify the returns field
3. Non-idempotent mutations - Check current state before updating
4. Reading before patching unnecessarily - Patch directly when possible
5. Not handling null returns - Document IDs might not exist

References

• Convex Documentation: https://docs.convex.dev/
• Convex LLMs.txt: https://docs.convex.dev/llms.txt
• Best Practices: https://docs.convex.dev/understanding/best-practices/
• Error Handling: https://docs.convex.dev/functions/error-handling
• Write Conflicts: https://docs.convex.dev/error#1