Convex Reactive Backend

This skill scaffolds and edits a production Convex backend from inside your project: a typed schema, server-side queries and mutations, actions for external I/O, scheduled functions, and the React hooks that bind it all to your UI. It's for developers building real-time apps (dashboards, chat, collaborative tools) who want a TypeScript backend without writing API endpoints, websocket plumbing, or cache-invalidation logic.

When to use it

• You're starting a new app and want a typed data layer where the frontend updates the instant data changes.
• You need server functions that read/write the database (mutation) plus ones that call third-party APIs or run Node code (action).
• You want scheduled work — sending a reminder N minutes after signup, nightly cleanup — via the scheduler or cron jobs.
• You're tired of react-query invalidation keys and want subscriptions handled for you.

How it works

Functions live in the convex/ directory and are deployed by npx convex dev, which watches files, pushes code, and regenerates types in convex/_generated/.

• Schema: convex/schema.ts uses defineSchema / defineTable with the v validator (v.string(), v.id("users"), v.optional(...)) and .index("by_author", ["authorId"]) for fast lookups.
• Queries & mutations: Export query/mutation from ./_generated/server. Read with ctx.db.query("messages").withIndex(...).collect(); write with ctx.db.insert/patch/replace/delete. Queries are reactive and cached; mutations are transactional.
• Actions: Use action for fetch, randomness, or "use node"; code. Actions can't touch ctx.db directly — they call queries/mutations via ctx.runQuery / ctx.runMutation.
• Scheduling: ctx.scheduler.runAfter(ms, api.module.fn, args) for delayed jobs; convex/crons.ts with crons.interval / crons.cron for recurring ones.
• React: useQuery(api.messages.list) subscribes and re-renders on change; useMutation(api.messages.send) returns a callable.

Usage

curl -fsSL --create-dirs -o ~/.claude/skills/convex-reactive-backend/SKILL.md https://claudeskil.com/skills/convex-reactive-backend/SKILL.md
npm install convex
npx convex dev   # provisions a dev deployment, watches convex/

// convex/messages.ts
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";

export const list = query({
  args: { channel: v.string() },
  handler: (ctx, { channel }) =>
    ctx.db.query("messages").withIndex("by_channel", q => q.eq("channel", channel)).collect(),
});

export const send = mutation({
  args: { channel: v.string(), body: v.string() },
  handler: (ctx, args) => ctx.db.insert("messages", args),
});

Tips & gotchas

• Define an index for any field you filter on; .filter() scans, .withIndex() doesn't.
• Mutations run in a transaction and may retry — keep them deterministic and side-effect-free; push fetch/email/Stripe into actions.
• Actions aren't transactional and can run more than once; make external calls idempotent.
• Wrap your tree in <ConvexProvider client={convex}>; useQuery returns undefined while loading, not null.

FAQ

Do I write REST endpoints? No. Exported functions are callable directly through generated, typed clients — though convex/http.ts exists if you need raw HTTP webhooks.

How is real-time handled? Convex tracks which queries read which data and pushes updates over a websocket; subscribed useQuery components re-render automatically.

Can I use my existing Postgres? Convex is its own document store, not a Postgres wrapper. Migrate data in via mutations or an import script.