Convex backend

Convex is the reactive backend that vly apps run on. Real-time queries, end-to-end TypeScript, queries / mutations / actions, file storage, vector search, and more.

Every app vly generates runs on Convex — a managed real-time backend with a serverless function model and a TypeScript-first developer experience. This page is the executive summary; for the full deep-dive, see Convex Deep Dive.

Why Convex

Reactive by default

Every Convex query auto-updates on the client when underlying data changes. No polling, no websocket plumbing, no refetch calls. Build a chat or a dashboard, and it’s live without effort.

End-to-end TypeScript

The schema is TypeScript. Queries return typed results. Your React component consumes the same types. No DTO mapping, no codegen, no client/server drift.

Serverless functions, no infra

Queries, mutations, actions, and scheduled functions run on Convex’s managed runtime. No containers to ship, no databases to provision.

Native primitives for hard things

File storage, vector search, full-text search, scheduled jobs, transactional mutations — all first-class, not bolted on.

The four function types

Queries

Read data. Reactive — clients subscribe and get updates automatically. Cannot mutate data.

Mutations

Write data, transactionally. ACID guarantees. Cannot call third-party APIs.

Actions

Call third-party APIs, run long-running work. Use process.env. Can run mutations and queries internally.

Scheduled functions

Cron-style or one-shot delayed execution. Common for retries, cleanups, reminders.

A minimal example

The schema:

convex/schema.ts

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  tasks: defineTable({
    title: v.string(),
    completed: v.boolean(),
    ownerId: v.id("users"),
    dueAt: v.optional(v.number()),
  })
    .index("by_owner", ["ownerId"])
    .index("by_owner_and_completed", ["ownerId", "completed"]),

  users: defineTable({
    email: v.string(),
    name: v.string(),
    avatarUrl: v.optional(v.string()),
    createdAt: v.number(),
  }).index("by_email", ["email"]),
});

A query:

convex/tasks.ts

import { query } from "./_generated/server";
import { v } from "convex/values";

export const listForOwner = query({
  args: { ownerId: v.id("users"), onlyOpen: v.optional(v.boolean()) },
  handler: async (ctx, { ownerId, onlyOpen }) => {
    const q = ctx.db
      .query("tasks")
      .withIndex(
        onlyOpen ? "by_owner_and_completed" : "by_owner",
        (q) => onlyOpen ? q.eq("ownerId", ownerId).eq("completed", false)
                        : q.eq("ownerId", ownerId),
      );
    return await q.collect();
  },
});

Call it from React:

const tasks = useQuery(api.tasks.listForOwner, { ownerId, onlyOpen: true });

A mutation:

convex/tasks.ts

import { mutation } from "./_generated/server";
import { v } from "convex/values";

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

export const toggle = mutation({
  args: { id: v.id("tasks") },
  handler: async (ctx, { id }) => {
    const task = await ctx.db.get(id);
    if (!task) throw new Error("Task not found");
    await ctx.db.patch(id, { completed: !task.completed });
  },
});

A React component using both:

components/TaskList.tsx

import { useQuery, useMutation } from "convex/react";
import { api } from "../convex/_generated/api";

export function TaskList({ ownerId }: { ownerId: Id<"users"> }) {
  const tasks  = useQuery(api.tasks.listForOwner, { ownerId, onlyOpen: true });
  const toggle = useMutation(api.tasks.toggle);

  if (tasks === undefined) return <div>Loading…</div>;

  return (
    <ul>
      {tasks.map((task) => (
        <li key={task._id}>
          <input
            type="checkbox"
            checked={task.completed}
            onChange={() => toggle({ id: task._id })}
          />
          {task.title}
        </li>
      ))}
    </ul>
  );
}

When toggle runs, every connected client viewing the same query updates immediately. No refetch, no manual invalidation.

How vly uses Convex

vly maps app concepts onto Convex concepts:

When you ask vly to “send an email when a task is assigned,” vly creates a Convex action (because actions can call external APIs), wires it into the assignment mutation, and adds the API key to your environment.

When you’ll edit Convex code

Most of the time, you won’t — vly handles it. But there are good reasons to drop into Code mode and edit a Convex file directly:

Adding an index for performance

A query is slow. You add .index("by_field", ["fieldName"]) to the schema, then re-prompt or hand-edit the query to use it. See Indexes.

Tweaking validation

Convex schema validators (v.string(), v.optional(...), v.union(...)) define what data shapes are allowed. Tightening or loosening these by hand is sometimes faster than prompting.

Custom action logic

Calling a third-party API with non-trivial logic — retries, custom serialization, complex auth flows. Hand-edit the action.

Reading the migration history

convex/_generated/ shows the current schema state; the schema files show your authored intent. When debugging schema drift, read both. See Migrations.

Limits

Convex isn’t infinite. The current limits:

Document size

1 MB max per document

These are well above what most vly apps need. If you’re approaching one, see Architecture: rate limiting and Patterns for scale.

Next

Convex deep dive

The full reference: schema, queries, mutations, actions, search, storage.

Real-time sync

How Convex’s reactive sync works under the hood.

Data modeling patterns

Schema patterns for the most common app shapes.