convex

name

convex

description

Expert guidance for Convex backend development including queries, mutations, actions, schemas, authentication, scheduling, file storage, search, and Next.js integration. Use when working with Convex functions, database operations, convex/ directory code, or Next.js App Router with Convex. Triggers: convex functions, ctx.db, useQuery, useMutation, usePreloadedQuery, preloadQuery, fetchQuery, convex schema, convex auth, convex cron, convex actions, convex scheduling, ctx.storage, generateUploadUrl, file upload, storage.store, storage.getUrl, Id<"_storage">, ConvexProvider, ConvexClientProvider, db.system, _scheduled_functions, _storage system table, OCC, optimistic concurrency, transaction atomicity, schema evolution, searchIndex, vectorIndex, withSearchIndex, ctx.vectorSearch, full-text search, vector search, embeddings, RAG, semantic search, typeahead search, ConvexError, httpAction, httpRouter, CORS, webhook.

Convex Backend Development

Core Architecture

Convex is a reactive database where queries are TypeScript functions. The sync engine (queries + mutations + database) is the heart of Convex — center your app around it.

Function Types

Type	DB Access	Deterministic	Cached/Reactive	Use For
query	Read only	Yes	Yes	All reads, subscriptions
mutation	Read/Write	Yes	No	All writes (transactions)
action	Via ctx.run*	No	No	External APIs, LLMs, email
httpAction	Via ctx.run*	No	No	Webhooks, custom HTTP

Key rule: Queries and mutations cannot make network requests. Actions cannot directly access the database.

Project Structure (Best Practice)

convex/
├── _generated/         # Auto-generated types (commit this)
├── schema.ts           # Database schema
├── model/              # Helper functions (most logic lives here)
│   ├── users.ts
│   └── messages.ts
├── users.ts            # Thin wrappers exposing public API
├── messages.ts
├── crons.ts            # Cron job definitions
└── http.ts             # HTTP action routes

Essential Patterns

1. Function Structure

// convex/messages.ts
import { query, mutation, internalMutation } from './_generated/server';
import { internal } from './_generated/api';
import { v } from 'convex/values';

// PUBLIC query with validators (always validate public functions)
export const list = query({
  args: { channelId: v.id('channels') },
  handler: async (ctx, { channelId }) => {
    return await ctx.db
      .query('messages')
      .withIndex('by_channel', (q) => q.eq('channelId', channelId))
      .order('desc')
      .take(50);
  }
});

// PUBLIC mutation with validators and auth check
export const send = mutation({
  args: { channelId: v.id('channels'), body: v.string() },
  handler: async (ctx, { channelId, body }) => {
    const user = await ctx.auth.getUserIdentity();
    if (!user) throw new Error('Unauthorized');

    await ctx.db.insert('messages', {
      channelId,
      body,
      authorId: user.subject
    });
  }
});

// INTERNAL mutation (for scheduling, crons, actions)
export const deleteOld = internalMutation({
  args: { before: v.number() },
  handler: async (ctx, { before }) => {
    const old = await ctx.db
      .query('messages')
      .withIndex('by_createdAt', (q) => q.lt('_creationTime', before))
      .take(100);
    for (const msg of old) {
      await ctx.db.delete(msg._id);
    }
  }
});

2. Helper Functions Pattern

Most logic should live in helper functions, NOT in query/mutation handlers:

// convex/model/users.ts
import { QueryCtx, MutationCtx } from '../_generated/server';
import { Doc } from '../_generated/dataModel';

export async function getCurrentUser(
  ctx: QueryCtx
): Promise<Doc<'users'> | null> {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) return null;

  return await ctx.db
    .query('users')
    .withIndex('by_tokenIdentifier', (q) =>
      q.eq('tokenIdentifier', identity.tokenIdentifier)
    )
    .unique();
}

export async function requireUser(ctx: QueryCtx): Promise<Doc<'users'>> {
  const user = await getCurrentUser(ctx);
  if (!user) throw new Error('Unauthorized');
  return user;
}

3. Actions with Scheduling

// convex/ai.ts
import { action, internalMutation } from './_generated/server';
import { internal } from './_generated/api';
import { v } from 'convex/values';

export const summarize = action({
  args: { documentId: v.id('documents') },
  handler: async (ctx, { documentId }) => {
    // Read data via internal query
    const doc = await ctx.runQuery(internal.documents.get, { documentId });

    // Call external API
    const response = await fetch('https://api.openai.com/v1/...', {...});
    const summary = await response.json();

    // Write result via internal mutation
    await ctx.runMutation(internal.documents.setSummary, {
      documentId,
      summary: summary.text
    });
  }
});

// Trigger action from mutation (not directly from client)
export const requestSummary = mutation({
  args: { documentId: v.id('documents') },
  handler: async (ctx, { documentId }) => {
    const user = await ctx.auth.getUserIdentity();
    if (!user) throw new Error('Unauthorized');

    await ctx.db.patch(documentId, { status: 'processing' });

    // Schedule action (runs after mutation commits)
    await ctx.scheduler.runAfter(0, internal.ai.summarizeInternal, {
      documentId
    });
  }
});

4. Application Errors

import { ConvexError } from 'convex/values';

export const assignRole = mutation({
  args: { roleId: v.id('roles'), userId: v.id('users') },
  handler: async (ctx, { roleId, userId }) => {
    const existing = await ctx.db
      .query('assignments')
      .withIndex('by_role', (q) => q.eq('roleId', roleId))
      .first();

    if (existing) {
      throw new ConvexError({
        code: 'ROLE_TAKEN',
        message: 'Role is already assigned'
      });
    }

    await ctx.db.insert('assignments', { roleId, userId });
  }
});

Critical Rules

DO ✅

• Use internal. functions for all ctx.run*, ctx.scheduler, and crons
• Always validate args for public functions with v.* validators
• Always check auth in public functions: ctx.auth.getUserIdentity()
• Use indexes with .withIndex() instead of .filter()
• Await all promises (enable no-floating-promises ESLint rule)
• Keep actions small — put logic in queries/mutations
• Batch database operations in single mutations
• Use ConvexError for user-facing errors

DON'T ❌

• Don't use api. functions for scheduling (use internal.)
• Don't use .filter() on queries — use indexes or TypeScript filter
• Don't use .collect() on unbounded queries (use .take() or pagination)
• Don't use Date.now() in queries (breaks caching)
• Don't call actions directly from client (trigger via mutation + scheduler)
• Don't make sequential ctx.runQuery/runMutation calls in actions (batch them)
• Don't use ctx.runAction unless switching runtimes (use helper functions)

Reference Guides

For detailed patterns, see:

• FUNCTIONS.md — Queries, mutations, actions, internal functions
• VALIDATION.md — Argument validation, extended validators
• ERROR_HANDLING.md — ConvexError, application errors
• HTTP_ACTIONS.md — HTTP actions, CORS, webhooks
• RUNTIMES.md — Default vs Node.js runtime, bundling, debugging
• DATABASE.md — Schema, indexes, reading/writing data
• SEARCH.md — Full-text search, vector search, RAG patterns
• ADVANCED.md — System tables, schema philosophy, OCC
• AUTH.md — Row-level security, Convex Auth (first-party)
• SCHEDULING.md — Crons, scheduled functions, workflows
• FILE_STORAGE.md — Upload, store, serve, delete files
• NEXTJS.md — Next.js App Router, SSR, Server Actions

Auth Provider Skills (add to project as needed):

• convex-auth — Universal auth patterns, storing users, debugging
• convex-clerk — Clerk setup, webhooks, JWT configuration
• convex-workos — WorkOS AuthKit setup, auto-provisioning