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
- powroom/flinsword for word, first seen Jan 22, 2026
Other versions1 project uses a version of this.
Word for word · 1
- powroom/flins★ 39100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository46 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- avoid-feature-creepSkill
- better-auth-best-practicesSkill
- Convex AgentsSkill
- Convex Best PracticesSkill
- Convex Component AuthoringSkill
- Convex Cron JobsSkill
- Convex File StorageSkill
- Convex FunctionsSkill
- Convex HTTP ActionsSkill
- Convex MigrationsSkill
- Convex RealtimeSkill
- Convex Schema ValidatorSkill
- Convex Security AuditSkill
- Convex Security CheckSkill
- create-auth-skillSkill
- avoid-feature-creepSkill
- better-auth-best-practicesSkill
- Convex AgentsSkill
- Convex Component AuthoringSkill
- Convex Cron JobsSkill
- Convex File StorageSkill
- Convex FunctionsSkill
- Convex HTTP ActionsSkill
- Convex MigrationsSkill
- Convex RealtimeSkill
- Convex Schema ValidatorSkill
- Convex Security AuditSkill
- Convex Security CheckSkill
- create-auth-skillSkill
- avoid-feature-creepSkill
- better-auth-best-practicesSkill
- Convex AgentsSkill
- Convex Best PracticesSkill
- Convex Component AuthoringSkill
- Convex Cron JobsSkill
- Convex File StorageSkill
- Convex FunctionsSkill
- Convex HTTP ActionsSkill
- Convex MigrationsSkill
- Convex RealtimeSkill
- Convex Schema ValidatorSkill
- Convex Security AuditSkill
- Convex Security CheckSkill
- create-auth-skillSkill
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
- Distinctive: line 15
Before implementing, do not assume.
- Distinctive: line 19
Write Conflicts: https://docs.convex.dev/error#1
- Distinctive: line 57
Always define validators for arguments AND return types:
- Distinctive: line 81
Use indexes instead of filters for efficient queries:
- Distinctive: line 117
Use ConvexError for user-facing errors:
- Very specific: line 309
Never run npx convex deploy unless explicitly instructed
- Distinctive: line 310
Never run any git commands unless explicitly instructed
- Distinctive: line 311
Always define return validators for functions
- Distinctive: line 312
Use indexes for all queries that filter data
- Distinctive: line 314
Use ConvexError for user-facing error messages
- Distinctive: line 316
Use internal functions for sensitive operations
- Distinctive: line 321
Using filter instead of withIndex: - Always define indexes and use withIndex
- Distinctive: line 322
Missing return validators: - Always specify the returns field
- Distinctive: line 323
Non-idempotent mutations: - Check current state before updating
- Distinctive: line 325
Not handling null returns: - Document IDs might not exist
≈ “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.
Files
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:
- 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
- Convex manages the hard parts - Let Convex handle caching, real-time sync, and consistency
- Functions are the API - Design your functions as your application's interface
- Schema is truth - Define your data model explicitly in schema.ts
- TypeScript everywhere - Leverage end-to-end type safety
- 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 deployunless 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
- Using filter instead of withIndex - Always define indexes and use withIndex
- Missing return validators - Always specify the returns field
- Non-idempotent mutations - Check current state before updating
- Reading before patching unnecessarily - Patch directly when possible
- 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
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
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.

