Build Reactive Backends with Convex

This skill acts as an expert in Convex, the open-source reactive backend platform where all backend logic is written in TypeScript, covering schema design, function authoring, real-time subscriptions, authentication, file storage, scheduling, and deployment across React, Next.js, Angular, Vue, Svelte, React Native, and server-side environments. Convex is document-relational with a fully managed backend: queries are reactive by default and automatically push updates to connected clients when data changes, all backend logic is TypeScript, writes run as ACID transactions with serializable isolation, there's no infrastructure to manage, and types flow end-to-end from schema through backend functions to client hooks.

Four function types cover different needs: queries read data and are cached/reactive; mutations write data as ACID transactions; actions handle side effects and external API calls but can only touch the database indirectly via runQuery/runMutation; and HTTP actions expose webhooks and custom endpoints with the same database-access constraint as actions. Schemas are defined with a validator library covering strings, numbers, booleans, document references, arrays, nested objects, unions, literals, and vector fields for embeddings:

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()),
    tokenIdentifier: v.string(),
  })
    .index("by_token", ["tokenIdentifier"])
    .index("by_email", ["email"]),
});

Indexes support single-field, compound (equality filters first, range filter last), full-text search, and vector search for AI embeddings. Setup is a two-command flow - install the package and run the dev CLI - which prompts a GitHub login, provisions a project and deployment, generates the backend folder, and syncs functions to the dev deployment in real time.

On the client side it covers React/Next.js integration via a Convex provider plus useQuery/useMutation/usePaginatedQuery hooks, and an Angular integration pattern using signals and dependency injection since there's no official Angular client. Authentication options include native Convex Auth (magic links, passwords, 80+ OAuth providers with no third-party service needed), third-party Clerk integration, and a community Better Auth component currently in early alpha. It covers one-off scheduled functions and recurring cron jobs, file storage via generated upload URLs, and environment variables (accessible only inside actions, never queries or mutations).

Best practices include always defining schemas, using indexes instead of .filter(), keeping external API calls in actions only, and validating all function arguments. Common anti-patterns flagged: calling external APIs from queries/mutations, slow CPU-bound work in mutations, unbounded .collect() on large tables, skipping schema definition, storing large blobs directly in documents instead of file storage, and circular runQuery/runMutation chains where an action calls a mutation that itself schedules more actions, which can create infinite loops.

A few troubleshooting pitfalls come up often enough to call out directly. A query returning undefined on first render is expected, not broken - Convex queries are async, so check for undefined before rendering rather than treating it as an empty result. A mutation throwing Document not found usually means the document was deleted between your read and write due to optimistic concurrency; re-read it inside the mutation rather than trusting a value fetched earlier. And time/randomness are safe to use directly inside queries and mutations - Date.now() and Math.random() are fully deterministic there because Convex freezes time at the start of every function execution.

Use it when building a new project on Convex, adding Convex to an existing frontend app, designing a Convex schema, writing or debugging Convex functions, implementing reactive data patterns, setting up authentication, working with file storage or cron jobs, or deploying and managing a Convex project.

Hard limitations: queries and mutations cannot call external HTTP APIs, there's no raw SQL, documents are capped at 1MB, and schema changes require migrating existing data.

Output is working Convex schema, function, and client-integration code across the supported frameworks, plus CLI commands for environment variables, deployment, data import/export, and log inspection.

Convex is TypeScript-first with ACID transactions, which the skill positions against Firebase's Firestore; it's document-relational with built-in reactivity, contrasted with a Supabase/PostgreSQL backend; and it replaces both an ORM like Prisma and the database itself rather than sitting on top of one. On the frontend it pairs with React patterns and the Next.js App Router. For authentication it supports native Convex Auth, third-party Clerk, or the community Better Auth component. For payments it integrates via actions and HTTP webhooks with providers like Stripe.

Full-stack developers building reactive applications who want a TypeScript-first backend with built-in real-time subscriptions, ACID transactions, and no separate database or ORM to manage.