agentleFS
charlietlambcharlietlamb/ferix/.cursor/skills/Convex Best Practices/SKILL.md

Convex Best Practices

Skill10 starsChanged 10 months agoMITView on GitHub

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

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. About 0 are common, 14 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈14

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before implementing, do not assume.

    line 15
  2. Distinctive:

    Write Conflicts: https://docs.convex.dev/error#1

    line 19
  3. Distinctive:

    Always define validators for arguments AND return types:

    line 57
  4. Distinctive:

    Use indexes instead of filters for efficient queries:

    line 81
  5. Distinctive:

    Use ConvexError for user-facing errors:

    line 117
  6. Very specific:

    Never run npx convex deploy unless explicitly instructed

    line 309
  7. Distinctive:

    Never run any git commands unless explicitly instructed

    line 310
  8. Distinctive:

    Always define return validators for functions

    line 311
  9. Distinctive:

    Use indexes for all queries that filter data

    line 312
  10. Distinctive:

    Use ConvexError for user-facing error messages

    line 314
  11. Distinctive:

    Use internal functions for sensitive operations

    line 316
  12. Distinctive:

    Using filter instead of withIndex: - Always define indexes and use withIndex

    line 321
  13. Distinctive:

    Missing return validators: - Always specify the returns field

    line 322
  14. Distinctive:

    Non-idempotent mutations: - Check current state before updating

    line 323
  15. Distinctive:

    Not handling null returns: - Document IDs might not exist

    line 325

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Convex Best Practices

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

Documentation Sources

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

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("users"),
    _creationTime: v.number(),
    name: v.string(),
    email: v.string(),
  }), v.null()),
  handler: async (ctx, args) => {
    return await ctx.db.get(args.userId);
  },
});

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.id("tasks"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("tasks", {
      title: args.title,
      description: args.description,
      priority: args.priority,
      completed: false,
      createdAt: Date.now(),
    });
  },
});

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"])
    .index("by_user_and_status", ["userId", "status"]),
});

// Query using index
export const getTasksByUser = query({
  args: { userId: v.id("users") },
  returns: v.array(v.object({
    _id: v.id("tasks"),
    _creationTime: v.number(),
    userId: v.id("users"),
    status: v.string(),
    createdAt: v.number(),
  })),
  handler: async (ctx, args) => {
    return await ctx.db
      .query("tasks")
      .withIndex("by_user", (q) => q.eq("userId", args.userId))
      .order("desc")
      .collect();
  },
});

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) => {
    const task = await ctx.db.get(args.taskId);
    
    if (!task) {
      throw new ConvexError({
        code: "NOT_FOUND",
        message: "Task not found",
      });
    }
    
    await ctx.db.patch(args.taskId, { title: args.title });
    return null;
  },
});

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, args) => {
    const task = await ctx.db.get(args.taskId);
    
    // Early return if already complete (idempotent)
    if (!task || task.status === "completed") {
      return null;
    }
    
    await ctx.db.patch(args.taskId, {
      status: "completed",
      completedAt: Date.now(),
    });
    return null;
  },
});

// GOOD: Patch directly without reading first when possible
export const updateNote = mutation({
  args: { id: v.id("notes"), content: v.string() },
  returns: v.null(),
  handler: async (ctx, args) => {
    // Patch directly - ctx.db.patch throws if document doesn't exist
    await ctx.db.patch(args.id, { content: args.content });
    return null;
  },
});

// GOOD: Use Promise.all for parallel independent updates
export const reorderItems = mutation({
  args: { itemIds: v.array(v.id("items")) },
  returns: v.null(),
  handler: async (ctx, args) => {
    const updates = args.itemIds.map((id, index) =>
      ctx.db.patch(id, { order: index })
    );
    await Promise.all(updates);
    return null;
  },
});

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, args) => {
    // ...
  },
});

// Internal function - only callable from other Convex functions
export const _updateUserStats = internalMutation({
  args: { userId: v.id("users") },
  returns: v.null(),
  handler: async (ctx, args) => {
    // ...
  },
});

Examples

Complete CRUD Pattern

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

const taskValidator = v.object({
  _id: v.id("tasks"),
  _creationTime: v.number(),
  title: v.string(),
  completed: v.boolean(),
  userId: v.id("users"),
});

export const list = query({
  args: { userId: v.id("users") },
  returns: v.array(taskValidator),
  handler: async (ctx, args) => {
    return await ctx.db
      .query("tasks")
      .withIndex("by_user", (q) => q.eq("userId", args.userId))
      .collect();
  },
});

export const create = mutation({
  args: {
    title: v.string(),
    userId: v.id("users"),
  },
  returns: v.id("tasks"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("tasks", {
      title: args.title,
      completed: false,
      userId: args.userId,
    });
  },
});

export const update = mutation({
  args: {
    taskId: v.id("tasks"),
    title: v.optional(v.string()),
    completed: v.optional(v.boolean()),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    const { taskId, ...updates } = args;
    
    // Remove undefined values
    const cleanUpdates = Object.fromEntries(
      Object.entries(updates).filter(([_, v]) => v !== undefined)
    );
    
    if (Object.keys(cleanUpdates).length > 0) {
      await ctx.db.patch(taskId, cleanUpdates);
    }
    return null;
  },
});

export const remove = mutation({
  args: { taskId: v.id("tasks") },
  returns: v.null(),
  handler: async (ctx, args) => {
    await ctx.db.delete(args.taskId);
    return null;
  },
});

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.