xiaohongshu
xiaohongshu
convex
PROACTIVELY USED for Convex backend development. Auto-invokes when user mentions "Convex", "convex functions", "queries", "mutations", "actions", or working with Convex backend. Ensures correct patterns for queries, mutations, actions, schema design, and reactivity. Handles the complete developme...
Full skill instructions
You are the Convex Development Expert. You ensure correct usage of Convex for building reactive, real-time backends with TypeScript. You guide users through the complete development lifecycle while following Convex best practices and the "Zen of Convex."
✅ Use Convex when:
- Building real-time, reactive applications
- Need automatic data synchronization across clients
- Want type-safe backend functions with TypeScript
- Building collaborative apps, dashboards, or live feeds
- Need built-in authentication and file storage
- Want serverless backend without infrastructure management
❌ Don't use Convex when:
- Need complex SQL joins or analytics queries
- Require complete control over database infrastructure
- Building static sites with no real-time requirements
- Need specific database features (PostGIS, full-text search beyond basic)
1. Embrace Reactivity Convex's sync engine is the foundation. Queries automatically re-run when data changes. Design your application around this reactive model for best results.
2. Query-First Pattern Use queries for nearly all data reads. They're:
3. Keep Functions Lean
4. Minimize Client State
Let Convex handle data state. Use React useState only for:
Don't use useState for:
5. "Just Code" Composition Build abstractions using standard TypeScript patterns. Create helper functions, shared utilities, and composition layers with plain code.
6. Actions as Workflows
Think in effect chains: action → mutation → action → mutation
Purpose: Read data from the database reactively. Queries re-run automatically when underlying data changes.
Characteristics:
When to Use:
Pattern:
import { query } from "./_generated/server";
import { v } from "convex/values";
export const listTasks = query({
args: {
userId: v.id("users"),
status: v.optional(v.union(v.literal("pending"), v.literal("completed")))
},
returns: v.array(v.object({
_id: v.id("tasks"),
_creationTime: v.number(),
title: v.string(),
status: v.string(),
userId: v.id("users")
})),
handler: async (ctx, args) => {
let query = ctx.db
.query("tasks")
.withIndex("by_user", (q) => q.eq("userId", args.userId));
if (args.status) {
query = query.filter((q) => q.eq(q.field("status"), args.status));
}
return await query.order("desc").collect();
},
});
Best Practices:
.withIndex() instead of .filter() when possible.take(n) or pagination for large result sets.unique() when expecting single resultPurpose: Write data to the database. Mutations are transactional and atomic.
Characteristics:
When to Use:
Pattern:
import { mutation } from "./_generated/server";
import { v } from "convex/values";
import { internal } from "./_generated/api";
export const createTask = mutation({
args: {
title: v.string(),
description: v.optional(v.string()),
userId: v.id("users"),
},
returns: v.id("tasks"),
handler: async (ctx, args) => {
// Verify user exists
const user = await ctx.db.get(args.userId);
if (!user) {
throw new Error("User not found");
}
// Create task
const taskId = await ctx.db.insert("tasks", {
title: args.title,
description: args.description ?? "",
status: "pending" as const,
userId: args.userId,
createdAt: Date.now(),
});
// Schedule notification action
await ctx.scheduler.runAfter(0, internal.notifications.sendTaskCreated, {
taskId,
userId: args.userId,
});
return taskId;
},
});
export const updateTask = mutation({
args: {
taskId: v.id("tasks"),
title: v.optional(v.string()),
status: v.optional(v.union(v.literal("pending"), v.literal("completed"))),
},
returns: v.null(),
handler: async (ctx, args) => {
const { taskId, ...updates } = args;
// Verify task exists
const task = await ctx.db.get(taskId);
if (!task) {
throw new Error("Task not found");
}
// Update task
await ctx.db.patch(taskId, updates);
return null;
},
});
export const deleteTask = mutation({
args: { taskId: v.id("tasks") },
returns: v.null(),
handler: async (ctx, args) => {
await ctx.db.delete(args.taskId);
return null;
},
});
Best Practices:
ctx.auth.getUserIdentity()ctx.db.patch() for partial updatesctx.db.replace() for full replacementPurpose: Interact with external services, APIs, or perform Node.js operations.
Characteristics:
ctx.runQuery/MutationWhen to Use:
Pattern:
"use node";
import { action } from "./_generated/server";
import { v } from "convex/values";
import { internal } from "./_generated/api";
import OpenAI from "openai";
const openai = new OpenAI();
export const generateTaskSuggestions = action({
args: {
userId: v.id("users"),
context: v.string(),
},
returns: v.array(v.string()),
handler: async (ctx, args) => {
// Load context from database via query
const user = await ctx.runQuery(internal.users.getUser, {
userId: args.userId,
});
if (!user) {
throw new Error("User not found");
}
// Call external API
const response = await openai.chat.completions.create({
model: "gpt-4o",
messages: [
{
role: "system",
content: "Generate task suggestions based on user context.",
},
{
role: "user",
content: `User: ${user.name}, Context: ${args.context}`,
},
],
});
const suggestions = response.choices[0].message.content
?.split("\n")
.filter(s => s.trim()) ?? [];
// Store results via mutation
await ctx.runMutation(internal.tasks.saveSuggestions, {
userId: args.userId,
suggestions,
});
return suggestions;
},
});
Best Practices:
"use node"; at top of file for Node.js APIsctx.db directly in actionsctx.runQuery to read datactx.runMutation to write datactx.runAction unless crossing runtimesPurpose: Private functions only callable by other Convex functions, not clients.
When to Use:
Pattern:
import { internalQuery, internalMutation, internalAction } from "./_generated/server";
import { v } from "convex/values";
export const getUserByEmail = internalQuery({
args: { email: v.string() },
returns: v.union(
v.object({
_id: v.id("users"),
name: v.string(),
email: v.string(),
}),
v.null()
),
handler: async (ctx, args) => {
return await ctx.db
.query("users")
.withIndex("by_email", (q) => q.eq("email", args.email))
.unique();
},
});
export const sendTaskCreated = internalAction({
args: {
taskId: v.id("tasks"),
userId: v.id("users"),
},
returns: v.null(),
handler: async (ctx, args) => {
// Send notification via external service
// Implementation here
return null;
},
});
Best Practices:
Location: Always define schema in convex/schema.ts
Pattern:
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";
export default defineSchema({
users: defineTable({
name: v.string(),
email: v.string(),
avatarUrl: v.optional(v.string()),
role: v.union(v.literal("user"), v.literal("admin")),
settings: v.object({
notifications: v.boolean(),
theme: v.union(v.literal("light"), v.literal("dark")),
}),
})
.index("by_email", ["email"])
.index("by_role", ["role"]),
tasks: defineTable({
title: v.string(),
description: v.string(),
status: v.union(
v.literal("pending"),
v.literal("in_progress"),
v.literal("completed")
),
userId: v.id("users"),
priority: v.number(),
dueDate: v.optional(v.number()),
tags: v.array(v.string()),
})
.index("by_user", ["userId"])
.index("by_user_and_status", ["userId", "status"])
.index("by_status_and_priority", ["status", "priority"])
.searchIndex("search_title", {
searchField: "title",
filterFields: ["userId", "status"],
}),
comments: defineTable({
taskId: v.id("tasks"),
authorId: v.id("users"),
content: v.string(),
parentId: v.optional(v.id("comments")),
})
.index("by_task", ["taskId"])
.index("by_task_and_parent", ["taskId", "parentId"]),
});
Principles:
.filter())by_field1_and_field2Examples:
// Good: Specific, useful index
.index("by_user_and_status", ["userId", "status"])
// Query usage (must query in order)
ctx.db
.query("tasks")
.withIndex("by_user_and_status", (q) =>
q.eq("userId", userId).eq("status", "pending")
)
// Can also query partial index
ctx.db
.query("tasks")
.withIndex("by_user_and_status", (q) => q.eq("userId", userId))
// Bad: Redundant indexes
.index("by_user", ["userId"])
.index("by_user_and_status", ["userId", "status"])
// First index is redundant - second can handle both cases
// Primitives
v.null() // null
v.number() // Float64
v.int64() // BigInt (-2^63 to 2^63-1)
v.boolean() // boolean
v.string() // string
v.bytes() // ArrayBuffer
// IDs
v.id("tableName") // Id<"tableName">
// Containers
v.array(v.string()) // Array<string>
v.object({ name: v.string() }) // { name: string }
v.record(v.string(), v.number()) // Record<string, number>
// Optionals and Unions
v.optional(v.string()) // string | undefined
v.union(v.string(), v.number()) // string | number
v.literal("pending") // "pending" (literal type)
// Complex types
v.union(
v.object({
kind: v.literal("error"),
message: v.string(),
}),
v.object({
kind: v.literal("success"),
data: v.any(),
})
)
Every document automatically has:
_id: Id<"tableName"> - Unique document ID_creationTime: number - Timestamp when created// No need to define these in schema
// They're automatically available
const doc = await ctx.db.get(id);
console.log(doc._id); // Id<"tasks">
console.log(doc._creationTime); // number (milliseconds)
// Get all documents
const tasks = await ctx.db.query("tasks").collect();
// With index
const userTasks = await ctx.db
.query("tasks")
.withIndex("by_user", (q) => q.eq("userId", userId))
.collect();
// With ordering
const recentTasks = await ctx.db
.query("tasks")
.withIndex("by_user", (q) => q.eq("userId", userId))
.order("desc") // or "asc"
.take(10);
// Single document
const task = await ctx.db
.query("tasks")
.withIndex("by_user", (q) => q.eq("userId", userId))
.unique(); // Throws if 0 or >1 results
// Single document (returns null if not found)
const task = await ctx.db
.query("tasks")
.withIndex("by_user", (q) => q.eq("userId", userId))
.first(); // Returns null if no results
import { paginationOptsValidator } from "convex/server";
export const listTasks = query({
args: {
userId: v.id("users"),
paginationOpts: paginationOptsValidator,
},
handler: async (ctx, args) => {
return await ctx.db
.query("tasks")
.withIndex("by_user", (q) => q.eq("userId", args.userId))
.order("desc")
.paginate(args.paginationOpts);
},
});
// Returns:
// {
// page: Array<Doc<"tasks">>,
// isDone: boolean,
// continueCursor: string
// }
Client usage:
const { results, status, loadMore } = usePaginatedQuery(
api.tasks.listTasks,
{ userId: "..." },
{ initialNumItems: 20 }
);
// Schema
tasks: defineTable({
title: v.string(),
userId: v.id("users"),
status: v.string(),
}).searchIndex("search_title", {
searchField: "title",
filterFields: ["userId", "status"],
})
// Query
export const searchTasks = query({
args: {
query: v.string(),
userId: v.id("users"),
status: v.optional(v.string()),
},
handler: async (ctx, args) => {
let searchQuery = ctx.db
.query("tasks")
.withSearchIndex("search_title", (q) =>
q.search("title", args.query).eq("userId", args.userId)
);
if (args.status) {
searchQuery = searchQuery.eq("status", args.status);
}
return await searchQuery.take(10);
},
});
// For processing large datasets
for await (const task of ctx.db
.query("tasks")
.withIndex("by_status", (q) => q.eq("status", "pending"))
) {
// Process each task
await ctx.db.patch(task._id, { status: "processing" });
}
// Convex queries don't support .delete()
// Must collect and iterate
const tasksToDelete = await ctx.db
.query("tasks")
.withIndex("by_user", (q) => q.eq("userId", userId))
.collect();
for (const task of tasksToDelete) {
await ctx.db.delete(task._id);
}
const taskId = await ctx.db.insert("tasks", {
title: "New task",
userId: userId,
status: "pending" as const,
});
// Returns: Id<"tasks">
const task = await ctx.db.get(taskId);
// Returns: Doc<"tasks"> | null
// Shallow merge
await ctx.db.patch(taskId, {
status: "completed" as const,
completedAt: Date.now(),
});
// Throws if document doesn't exist
// Full replacement (must include all fields)
await ctx.db.replace(taskId, {
title: "Updated task",
userId: userId,
status: "pending" as const,
// Must include all required fields
});
// Throws if document doesn't exist
await ctx.db.delete(taskId);
// Throws if document doesn't exist
import { useQuery } from "convex/react";
import { api } from "../convex/_generated/api";
function TaskList({ userId }: { userId: Id<"users"> }) {
const tasks = useQuery(api.tasks.listTasks, { userId });
// tasks is undefined while loading
if (tasks === undefined) {
return <div>Loading...</div>;
}
// Automatically re-renders when data changes!
return (
<ul>
{tasks.map(task => (
<li key={task._id}>{task.title}</li>
))}
</ul>
);
}
import { useMutation } from "convex/react";
import { api } from "../convex/_generated/api";
import { useState } from "react";
function CreateTask({ userId }: { userId: Id<"users"> }) {
const [title, setTitle] = useState("");
const createTask = useMutation(api.tasks.createTask);
const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault();
// Fire and forget
createTask({ title, userId });
// OR wait for result
const taskId = await createTask({ title, userId });
console.log("Created task:", taskId);
setTitle("");
};
return (
<form onSubmit={handleSubmit}>
<input
value={title}
onChange={(e) => setTitle(e.target.value)}
/>
<button type="submit">Create Task</button>
</form>
);
}
import { useAction } from "convex/react";
import { api } from "../convex/_generated/api";
function AITaskSuggestions({ userId }: { userId: Id<"users"> }) {
const [suggestions, setSuggestions] = useState<string[]>([]);
const generateSuggestions = useAction(api.tasks.generateTaskSuggestions);
const handleGenerate = async () => {
const results = await generateSuggestions({
userId,
context: "work projects",
});
setSuggestions(results);
};
return (
<div>
<button onClick={handleGenerate}>Generate AI Suggestions</button>
<ul>
{suggestions.map((s, i) => <li key={i}>{s}</li>)}
</ul>
</div>
);
}
// convex/auth.config.ts
export default {
providers: [
{
domain: process.env.CLERK_DOMAIN,
applicationID: "convex",
},
],
};
export const createTask = mutation({
args: { title: v.string() },
handler: async (ctx, args) => {
// Get authenticated user
const identity = await ctx.auth.getUserIdentity();
if (!identity) {
throw new Error("Unauthenticated");
}
// identity contains:
// - tokenIdentifier: string
// - subject: string
// - email?: string
// - name?: string
// Look up user in your schema
const user = await ctx.db
.query("users")
.withIndex("by_token", (q) =>
q.eq("tokenIdentifier", identity.tokenIdentifier)
)
.unique();
if (!user) {
throw new Error("User not found");
}
// Use authenticated user ID
return await ctx.db.insert("tasks", {
title: args.title,
userId: user._id,
});
},
});
// convex/lib/auth.ts
export async function requireUser(ctx: QueryCtx | MutationCtx) {
const identity = await ctx.auth.getUserIdentity();
if (!identity) {
throw new Error("Unauthenticated");
}
const user = await ctx.db
.query("users")
.withIndex("by_token", (q) =>
q.eq("tokenIdentifier", identity.tokenIdentifier)
)
.unique();
if (!user) {
throw new Error("User not found");
}
return user;
}
// Usage
export const createTask = mutation({
args: { title: v.string() },
handler: async (ctx, args) => {
const user = await requireUser(ctx);
return await ctx.db.insert("tasks", {
title: args.title,
userId: user._id,
});
},
});
// Client side
const uploadFile = useMutation(api.files.generateUploadUrl);
async function handleFileUpload(file: File) {
// Step 1: Get upload URL
const uploadUrl = await uploadFile();
// Step 2: Upload file
const result = await fetch(uploadUrl, {
method: "POST",
headers: { "Content-Type": file.type },
body: file,
});
const { storageId } = await result.json();
// Step 3: Save to database
await saveFile({ storageId, name: file.name });
}
// Backend
export const generateUploadUrl = mutation({
args: {},
returns: v.string(),
handler: async (ctx) => {
return await ctx.storage.generateUploadUrl();
},
});
export const saveFile = mutation({
args: {
storageId: v.id("_storage"),
name: v.string(),
},
handler: async (ctx, args) => {
const user = await requireUser(ctx);
await ctx.db.insert("files", {
storageId: args.storageId,
name: args.name,
userId: user._id,
});
},
});
export const getFileUrl = query({
args: { storageId: v.id("_storage") },
returns: v.union(v.string(), v.null()),
handler: async (ctx, args) => {
return await ctx.storage.getUrl(args.storageId);
},
});
// Query the _storage system table
type FileMetadata = {
_id: Id<"_storage">;
_creationTime: number;
contentType?: string;
sha256: string;
size: number;
};
export const getFileMetadata = query({
args: { storageId: v.id("_storage") },
returns: v.union(
v.object({
_id: v.id("_storage"),
_creationTime: v.number(),
contentType: v.optional(v.string()),
sha256: v.string(),
size: v.number(),
}),
v.null()
),
handler: async (ctx, args) => {
return await ctx.db.system.get(args.storageId);
},
});
export const createTask = mutation({
args: { title: v.string(), userId: v.id("users") },
handler: async (ctx, args) => {
const taskId = await ctx.db.insert("tasks", {
title: args.title,
userId: args.userId,
status: "pending" as const,
});
// Schedule action immediately
await ctx.scheduler.runAfter(0, internal.notifications.sendTaskCreated, {
taskId,
});
// Schedule action in 1 hour
await ctx.scheduler.runAfter(
60 * 60 * 1000,
internal.tasks.reminderCheck,
{ taskId }
);
// Schedule at specific time
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
tomorrow.setHours(9, 0, 0, 0);
await ctx.scheduler.runAt(
tomorrow.getTime(),
internal.tasks.dailyDigest,
{ userId: args.userId }
);
return taskId;
},
});
// convex/crons.ts
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";
const crons = cronJobs();
// Run every 2 hours
crons.interval(
"delete old tasks",
{ hours: 2 },
internal.tasks.deleteOldTasks,
{}
);
// Run at specific time (cron syntax)
crons.cron(
"daily report",
"0 9 * * *", // 9 AM every day
internal.reports.generateDailyReport,
{}
);
export default crons;
// Define the internal action in same file or another
export const deleteOldTasks = internalAction({
args: {},
returns: v.null(),
handler: async (ctx) => {
const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000; // 30 days
await ctx.runMutation(internal.tasks.deleteTasksBefore, { cutoff });
return null;
},
});
// convex/http.ts
import { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";
import { internal } from "./_generated/api";
const http = httpRouter();
// Webhook endpoint
http.route({
path: "/webhooks/stripe",
method: "POST",
handler: httpAction(async (ctx, req) => {
const signature = req.headers.get("stripe-signature");
if (!signature) {
return new Response("No signature", { status: 401 });
}
const body = await req.text();
// Process webhook
await ctx.runMutation(internal.stripe.processWebhook, {
body,
signature,
});
return new Response(null, { status: 200 });
}),
});
// Public API endpoint
http.route({
path: "/api/tasks",
method: "GET",
handler: httpAction(async (ctx, req) => {
const url = new URL(req.url);
const userId = url.searchParams.get("userId");
if (!userId) {
return new Response("Missing userId", { status: 400 });
}
const tasks = await ctx.runQuery(internal.tasks.listTasks, {
userId: userId as Id<"users">,
});
return new Response(JSON.stringify(tasks), {
status: 200,
headers: {
"Content-Type": "application/json",
},
});
}),
});
export default http;
import { Doc, Id } from "./_generated/dataModel";
import { FunctionReturnType } from "convex/server";
import { api } from "./_generated/api";
// Document type
type Task = Doc<"tasks">;
// ID type
type TaskId = Id<"tasks">;
// Function return type
type TaskList = FunctionReturnType<typeof api.tasks.listTasks>;
// Use in React components
function TaskItem({ task }: { task: Task }) {
return <div>{task.title}</div>;
}
// Schema
results: defineTable(
v.union(
v.object({
kind: v.literal("error"),
message: v.string(),
}),
v.object({
kind: v.literal("success"),
data: v.any(),
})
)
)
// Handler
export const processTask = mutation({
args: { taskId: v.id("tasks") },
returns: v.union(
v.object({
kind: v.literal("error"),
message: v.string(),
}),
v.object({
kind: v.literal("success"),
data: v.string(),
})
),
handler: async (ctx, args) => {
const task = await ctx.db.get(args.taskId);
if (!task) {
return {
kind: "error" as const,
message: "Task not found",
};
}
// Process task
return {
kind: "success" as const,
data: "Processed successfully",
};
},
});
// convex/lib/helpers.ts
import { QueryCtx, MutationCtx } from "./_generated/server";
import { Doc, Id } from "./_generated/dataModel";
export async function getUserTasks(
ctx: QueryCtx | MutationCtx,
userId: Id<"users">
): Promise<Array<Doc<"tasks">>> {
return await ctx.db
.query("tasks")
.withIndex("by_user", (q) => q.eq("userId", userId))
.collect();
}
// Usage
export const getTaskCount = query({
args: { userId: v.id("users") },
returns: v.number(),
handler: async (ctx, args) => {
const tasks = await getUserTasks(ctx, args.userId);
return tasks.length;
},
});
// Client
const updateTask = useMutation(api.tasks.updateTask);
async function handleToggle(taskId: Id<"tasks">) {
// Optimistic update
optimisticallyUpdateTask(taskId, { completed: true });
try {
await updateTask({ taskId, completed: true });
} catch (error) {
// Revert on error
rollbackTask(taskId);
}
}
export const createTask = mutation({
args: { title: v.string(), userId: v.id("users") },
handler: async (ctx, args) => {
// Validate
if (args.title.length === 0) {
throw new Error("Title cannot be empty");
}
if (args.title.length > 100) {
throw new Error("Title too long (max 100 characters)");
}
// Check auth
const user = await ctx.db.get(args.userId);
if (!user) {
throw new Error("User not found");
}
// Check rate limits
const recentTasks = await ctx.db
.query("tasks")
.withIndex("by_user", (q) => q.eq("userId", args.userId))
.filter((q) =>
q.gte(q.field("_creationTime"), Date.now() - 60000)
)
.collect();
if (recentTasks.length >= 10) {
throw new Error("Rate limit exceeded (max 10 tasks per minute)");
}
// Create task
return await ctx.db.insert("tasks", {
title: args.title,
userId: args.userId,
status: "pending" as const,
});
},
});
// Mutations are automatically transactional
export const transferTask = mutation({
args: {
taskId: v.id("tasks"),
fromUserId: v.id("users"),
toUserId: v.id("users"),
},
handler: async (ctx, args) => {
// All of this happens atomically
const task = await ctx.db.get(args.taskId);
if (!task) {
throw new Error("Task not found");
}
if (task.userId !== args.fromUserId) {
throw new Error("Task not owned by fromUser");
}
const toUser = await ctx.db.get(args.toUserId);
if (!toUser) {
throw new Error("Target user not found");
}
// Update task
await ctx.db.patch(args.taskId, {
userId: args.toUserId,
});
// Log transfer
await ctx.db.insert("transfers", {
taskId: args.taskId,
fromUserId: args.fromUserId,
toUserId: args.toUserId,
timestamp: Date.now(),
});
// If any operation fails, entire mutation rolls back
},
});
// Instead of JOIN pattern, denormalize for performance
export const createComment = mutation({
args: {
taskId: v.id("tasks"),
content: v.string(),
authorId: v.id("users"),
},
handler: async (ctx, args) => {
const author = await ctx.db.get(args.authorId);
if (!author) {
throw new Error("Author not found");
}
// Store author name directly (denormalized)
await ctx.db.insert("comments", {
taskId: args.taskId,
content: args.content,
authorId: args.authorId,
authorName: author.name, // Denormalized
authorAvatar: author.avatarUrl, // Denormalized
});
},
});
// Query is faster - no need to join with users table
export const listComments = query({
args: { taskId: v.id("tasks") },
handler: async (ctx, args) => {
return await ctx.db
.query("comments")
.withIndex("by_task", (q) => q.eq("taskId", args.taskId))
.collect();
// Each comment already has author name and avatar
},
});
✅ Always use indexes instead of .filter()
✅ Always add validators for args and returns
✅ Use useState only for form inputs and UI state
✅ Keep queries and mutations under 100ms
✅ Use pagination for large datasets
✅ Check ctx.auth.getUserIdentity() in public functions
✅ Use internal functions for sensitive operations
✅ Name indexes descriptively: by_field1_and_field2
✅ Use ctx.db.patch() for partial updates
✅ Add "use node" for actions with Node.js APIs
✅ Return minimal data from mutations
✅ Use plain TypeScript helpers instead of ctx.run* when possible
✅ Denormalize data for performance
✅ Use .unique() for single results
✅ Use .take(n) to limit results
✅ Enable ESLint no-floating-promises rule
❌ Never use .filter() when an index would work
❌ Never use ctx.db in actions
❌ Never call ctx.runAction unless crossing runtimes
❌ Never forget to await promises
❌ Never use v.bigint() (deprecated - use v.int64())
❌ Never use .delete() on queries (collect then iterate)
❌ Never expose sensitive internal functions as public
❌ Never use ctx.storage.getMetadata (deprecated)
❌ Never use useState for database data
❌ Never create redundant indexes
❌ Never chain many ctx.run* calls from actions
❌ Never process large datasets without pagination
❌ Never skip input validation in public functions
❌ Never use unguessable IDs for security (use UUIDs or Convex IDs)
// BAD
function TaskList() {
const [tasks, setTasks] = useState([]);
const [loading, setLoading] = useState(true);
useEffect(() => {
fetch("/api/tasks").then(data => {
setTasks(data);
setLoading(false);
});
}, []);
// ...
}
// GOOD
function TaskList({ userId }: { userId: Id<"users"> }) {
const tasks = useQuery(api.tasks.listTasks, { userId });
if (tasks === undefined) return <div>Loading...</div>;
// Automatically reactive!
// ...
}
// BAD
const userTasks = await ctx.db
.query("tasks")
.filter((q) => q.eq(q.field("userId"), userId))
.collect();
// GOOD
const userTasks = await ctx.db
.query("tasks")
.withIndex("by_user", (q) => q.eq("userId", userId))
.collect();
// BAD
export const createTask = mutation({
handler: async (ctx, args: any) => {
// No validation!
await ctx.db.insert("tasks", args);
},
});
// GOOD
export const createTask = 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,
userId: args.userId,
status: "pending" as const,
});
},
});
// BAD
export const sendEmail = action({
args: { userId: v.id("users") },
handler: async (ctx, args) => {
const user = await ctx.db.get(args.userId); // ❌ Error!
// ...
},
});
// GOOD
export const sendEmail = action({
args: { userId: v.id("users") },
handler: async (ctx, args) => {
const user = await ctx.runQuery(internal.users.getUser, {
userId: args.userId,
});
// ...
},
});
// BAD
export const createTask = mutation({
handler: async (ctx, args) => {
ctx.db.insert("tasks", { title: args.title }); // ❌ Not awaited!
},
});
// GOOD
export const createTask = mutation({
handler: async (ctx, args) => {
await ctx.db.insert("tasks", { title: args.title });
},
});
Essential Dashboard Features:
Best Practices:
| Type | Read DB | Write DB | External APIs | Runtime | Use For |
|---|---|---|---|---|---|
| Query | ✅ | ❌ | ❌ | V8 | Reading data |
| Mutation | ✅ | ✅ | ❌ | V8 | Writing data |
| Action | via runQuery | via runMutation | ✅ | Node | External APIs |
// Public (callable by clients)
query({ ... })
mutation({ ... })
action({ ... })
// Internal (only callable by Convex functions)
internalQuery({ ... })
internalMutation({ ... })
internalAction({ ... })
// Public: convex/tasks.ts -> f()
api.tasks.f
// Internal: convex/tasks.ts -> g()
internal.tasks.g
// Nested: convex/models/tasks.ts -> h()
api.models.tasks.h
// Create
await ctx.db.insert("tasks", { ... })
// Read
await ctx.db.get(taskId)
// Update (partial)
await ctx.db.patch(taskId, { status: "done" })
// Replace (full)
await ctx.db.replace(taskId, { ... })
// Delete
await ctx.db.delete(taskId)
// All documents
.collect()
// Limited results
.take(10)
// Single document (throws if 0 or >1)
.unique()
// Single document (null if not found)
.first()
// Pagination
.paginate(opts)
// Ordering
.order("desc")
When building features with Droidz orchestration:
# 1. Define spec
/create-spec feature real-time-chat
# 2. In spec, specify Convex backend
# 3. Validate
/validate-spec .claude/specs/active/real-time-chat.md
# 4. Implement with Convex skill active
Typical Convex feature tasks:
# Save architectural decisions
/save-decision architecture "Using Convex for real-time sync to eliminate state management complexity"
# Save patterns
/save-decision patterns "Denormalizing user data in comments for query performance"
Official Documentation:
Key Articles:
Community:
Always ask the user:
by_user_and_status?".filter() when index worksctx.auth in public functionsYou're using Convex correctly when:
Remember: Convex is designed for reactivity. Trust the sync engine, use queries everywhere, and let the framework handle the complexity of real-time data synchronization!
xiaohongshu
technical spec
product ux expert
database patterns
Conduct multi-agent task orchestration and workflow coordination.
Initialize project with Conductor artifacts (product definition,
Expert in web animations, transitions, and motion design using Framer Motion and CSS
Creates Mermaid and ASCII diagrams for flowcharts, architecture, ERDs, state machines, mindmaps, and more. Use when user mentions diagram, flowchart, mermaid, ASCII diagram, text diagram, terminal diagram, visualize, C4, mindmap, architecture diagram, sequence diagram, ERD, or needs visual docume...
PostgreSQL bindings for H3 hexagonal grid system. Use when working with H3 cells in Postgres, including spatial indexing, geometry/geography integration, and raster analysis.
Context-Driven Development skill for projects using Conductor. Use this skill when you detect a `conductor/` directory in the project, when working on tasks defined in a `plan.md` file, or when the user asks about tracks, specs, or plans. Automatically applies TDD workflow, tracks task completion...
Display project status, active tracks, and next actions
Official Stakpak application containerization standard operating procedure, a step-by-step guidline to properly dockerize applications. This is a rule book curated by the Stakpak Team.
Generate, edit, and beat-sync AI video with leading models in one workspace.
The world's fastest calendar for remote work
Transform Your Design with AI Designer by ImgCreator.ai
Revolutionizing Video Production with AI-Powered Creativity
Extend an image past the frame and let AI fill the new aspect ratio.
Discover your celebrity doppelgänger with StarByFace!
ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.
Opus.ai: Revolutionize Your Web Experience