Articles/App Development

▣ App Development/2026-04-11Advanced

Building Real-Time Collaborative SaaS with Antigravity and Convex: From Type-Safe Data Sync to Stripe Billing

Build a real-time collaborative SaaS with Antigravity IDE and Convex — schema design, Clerk auth, file storage, Stripe billing, and the webhook implementation that quietly fails on Convex, with the fix.

convex saas¹⁰ realtime⁴ stripe⁹ clerk antigravity⁴⁴⁹ app-dev⁵¹

✦ Premium Article

Setup and context: Why Convex + Antigravity?

For indie developers and small teams, shipping a real-time collaborative SaaS has always been a slow project. But the slow part is rarely the syncing itself. Getting edits to flow between tabs takes a few days at most.

When I built document sharing into one of my own products, the flow-between-tabs part worked on day two. The remaining five days went to a single symptom: close a tab, reopen it, and one side's edits are gone. Missed writes on reconnect, merging what happened while offline, subscriptions that never got torn down. That's where the time actually goes.

Convex changes that ratio. It's a reactive backend where type-safe schema definitions, automatic subscription management, and serverless function execution are one system — and you write zero lines of WebSocket code on the client. Pair it with Antigravity IDE and the loop that shortens most visibly is the one after a schema change, when you have to chase every caller that just broke.

What follows builds a real-time collaborative document editor as a SaaS on Convex and Antigravity: Clerk for authentication, Convex's built-in storage for file uploads, Stripe for subscriptions, and a deploy to Cloudflare Pages. The finish line is an app that can actually take money.

There's one detour along the way. The Stripe webhook implementation you'll find in most write-ups — a Next.js Route Handler calling into Convex — does not work on Convex. TypeScript won't tell you. You find out when your Stripe dashboard fills up with 500s. I hit this in production, so I'll put the naive version down first and then take apart the three reasons it fails.

1. Project Setup

1-1. Prerequisites

# Node.js 20+ required
node --version  # v20.x.x or higher
 
# pnpm recommended
npm install -g pnpm
 
# Convex CLI
pnpm add -g convex

Open Antigravity IDE and ask the Agent to scaffold your project:

Create a new project called "CollabDocs" using Next.js 14, Convex, Clerk,
Stripe, and Tailwind CSS. Use TypeScript strict mode throughout.

The Agent will automatically run the setup commands:

pnpm create next-app@latest collabdocs \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*"
 
cd collabdocs
 
# Install dependencies
pnpm add convex @clerk/nextjs stripe @stripe/stripe-js
pnpm add -D @types/stripe

1-2. Initialize Convex

cd collabdocs
npx convex dev

The first run opens your browser to the Convex dashboard for authentication. Once you log in, your project is automatically created and the following environment variable is added to .env.local:

NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud

1-3. Ask Antigravity to Design Your Schema

Your schema is the backbone of your SaaS. Ask Antigravity's Agent:

Design a Convex schema for a real-time collaborative document SaaS.
I need the following entities:
- Users (synced from Clerk)
- Workspaces (multiple users can join)
- Documents (belong to a workspace)
- Document operation history (for real-time sync)
- Subscription information

Review what the Agent generates and refine as needed.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Developers stuck on Convex real-time sync can complete their data architecture in a single day with Antigravity's AI assistance

✦Learn the code patterns a production SaaS actually needs — schema design, Clerk auth, file storage, and Stripe billing wired end to end

✦Walk away with the technical skills and design judgment to ship a revenue-generating web app using Convex and Antigravity

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

2. Convex Schema Design

2-1. Table Definitions

Create convex/schema.ts:

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";
 
export default defineSchema({
  // Users table (synced from Clerk)
  users: defineTable({
    clerkId: v.string(),
    email: v.string(),
    name: v.string(),
    imageUrl: v.optional(v.string()),
    plan: v.union(v.literal("free"), v.literal("pro")),
    stripeCustomerId: v.optional(v.string()),
    stripeSubscriptionId: v.optional(v.string()),
    createdAt: v.number(),
  })
    .index("by_clerk_id", ["clerkId"])
    .index("by_email", ["email"]),
 
  // Workspaces table
  workspaces: defineTable({
    name: v.string(),
    ownerId: v.id("users"),
    plan: v.union(v.literal("free"), v.literal("pro")),
    memberIds: v.array(v.id("users")),
    createdAt: v.number(),
    updatedAt: v.number(),
  })
    .index("by_owner", ["ownerId"]),
 
  // Documents table
  documents: defineTable({
    title: v.string(),
    content: v.string(),       // JSON string (editor internal format)
    workspaceId: v.id("workspaces"),
    authorId: v.id("users"),
    collaboratorIds: v.array(v.id("users")),
    storageId: v.optional(v.id("_storage")),  // attached file
    isPublic: v.boolean(),
    createdAt: v.number(),
    updatedAt: v.number(),
  })
    .index("by_workspace", ["workspaceId"])
    .index("by_author", ["authorId"]),
 
  // Operation history (for OT / CRDT-based diff recording)
  documentOperations: defineTable({
    documentId: v.id("documents"),
    userId: v.id("users"),
    operation: v.string(),     // JSON string (diff data)
    version: v.number(),
    timestamp: v.number(),
  })
    .index("by_document", ["documentId"])
    .index("by_document_version", ["documentId", "version"]),
});

2-2. Schema Design Insights from Antigravity

Ask Antigravity to review your schema: "What are the potential issues with this schema and how can I improve it?" You'll get feedback like:

The content field stored as a string works, but using v.any() or a dedicated type improves type safety
The memberIds array can become a performance bottleneck for large workspaces — consider a junction table
documentOperations benefits from a composite index on ["documentId", "timestamp"] for time-ordered queries

This kind of iterative AI-assisted schema refinement is where Antigravity really shines.

3. Queries, Mutations, and Actions

3-1. Document CRUD

Create convex/documents.ts:

import { query, mutation } from "./_generated/server";
import { v } from "convex/values";
import { getCurrentUser } from "./users";
 
// List documents (automatically real-time synced)
export const listByWorkspace = query({
  args: { workspaceId: v.id("workspaces") },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    if (!user) return [];
 
    const docs = await ctx.db
      .query("documents")
      .withIndex("by_workspace", (q) =>
        q.eq("workspaceId", args.workspaceId)
      )
      .order("desc")
      .collect();
 
    return docs.filter(
      (doc) =>
        doc.isPublic ||
        doc.authorId === user._id ||
        doc.collaboratorIds.includes(user._id)
    );
  },
});
 
// Create a document
export const create = mutation({
  args: {
    title: v.string(),
    workspaceId: v.id("workspaces"),
  },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    if (!user) throw new Error("Authentication required");
 
    const now = Date.now();
    return await ctx.db.insert("documents", {
      title: args.title,
      content: JSON.stringify({ type: "doc", content: [] }),
      workspaceId: args.workspaceId,
      authorId: user._id,
      collaboratorIds: [],
      isPublic: false,
      createdAt: now,
      updatedAt: now,
    });
  },
});
 
// Update content (the core of real-time sync)
export const updateContent = mutation({
  args: {
    documentId: v.id("documents"),
    content: v.string(),
    operation: v.string(),   // diff data
  },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    if (!user) throw new Error("Authentication required");
 
    const doc = await ctx.db.get(args.documentId);
    if (!doc) throw new Error("Document not found");
 
    const canEdit =
      doc.authorId === user._id ||
      doc.collaboratorIds.includes(user._id);
    if (!canEdit) throw new Error("Edit permission denied");
 
    const now = Date.now();
 
    await ctx.db.patch(args.documentId, {
      content: args.content,
      updatedAt: now,
    });
 
    const lastOp = await ctx.db
      .query("documentOperations")
      .withIndex("by_document", (q) =>
        q.eq("documentId", args.documentId)
      )
      .order("desc")
      .first();
 
    await ctx.db.insert("documentOperations", {
      documentId: args.documentId,
      userId: user._id,
      operation: args.operation,
      version: (lastOp?.version ?? 0) + 1,
      timestamp: now,
    });
  },
});

3-2. How Real-Time Sync Works

Convex's killer feature is that queries automatically stay in sync in real time. Using useQuery in your React components means that when any data changes on the server, the UI updates immediately — no manual polling, no WebSocket management.

// app/workspace/[id]/page.tsx
"use client";
 
import { useQuery } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";
 
export default function WorkspacePage({
  params,
}: {
  params: { id: string };
}) {
  // This query re-runs automatically whenever the data changes
  const documents = useQuery(api.documents.listByWorkspace, {
    workspaceId: params.id as Id<"workspaces">,
  });
 
  if (documents === undefined) {
    return <div className="animate-pulse">Loading...</div>;
  }
 
  return (
    <div className="grid gap-4 p-6">
      {documents.map((doc) => (
        <DocumentCard key={doc._id} document={doc} />
      ))}
    </div>
  );
}

When User A calls updateContent, User B's screen — open in another tab or browser — updates automatically within milliseconds.

4. Clerk Authentication Integration

4-1. Clerk + Convex Configuration

// convex/auth.config.ts
export default {
  providers: [
    {
      domain: process.env.CLERK_JWT_ISSUER_DOMAIN!,
      applicationID: "convex",
    },
  ],
};

// convex/users.ts
import { internalMutation, query, QueryCtx } from "./_generated/server";
import { v } from "convex/values";
 
export const getCurrentUser = async (ctx: QueryCtx) => {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) return null;
 
  return await ctx.db
    .query("users")
    .withIndex("by_clerk_id", (q) =>
      q.eq("clerkId", identity.subject)
    )
    .unique();
};
 
export const syncUser = internalMutation({
  args: {
    clerkId: v.string(),
    email: v.string(),
    name: v.string(),
    imageUrl: v.optional(v.string()),
  },
  handler: async (ctx, args) => {
    const existing = await ctx.db
      .query("users")
      .withIndex("by_clerk_id", (q) => q.eq("clerkId", args.clerkId))
      .unique();
 
    if (existing) {
      await ctx.db.patch(existing._id, {
        email: args.email,
        name: args.name,
        imageUrl: args.imageUrl,
      });
      return existing._id;
    }
 
    return await ctx.db.insert("users", {
      ...args,
      plan: "free",
      createdAt: Date.now(),
    });
  },
});

4-2. Clerk Webhook Handler

Create app/api/clerk/webhook/route.ts:

import { Webhook } from "svix";
import { headers } from "next/headers";
import { WebhookEvent } from "@clerk/nextjs/server";
import { ConvexHttpClient } from "convex/browser";
import { api } from "@/convex/_generated/api";
 
const convex = new ConvexHttpClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
 
export async function POST(req: Request) {
  const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET;
  if (!WEBHOOK_SECRET) {
    throw new Error("CLERK_WEBHOOK_SECRET not set");
  }
 
  const headerPayload = headers();
  const svix_id = headerPayload.get("svix-id");
  const svix_timestamp = headerPayload.get("svix-timestamp");
  const svix_signature = headerPayload.get("svix-signature");
 
  if (!svix_id || !svix_timestamp || !svix_signature) {
    return new Response("Bad Request", { status: 400 });
  }
 
  const payload = await req.json();
  const body = JSON.stringify(payload);
  const wh = new Webhook(WEBHOOK_SECRET);
  let evt: WebhookEvent;
 
  try {
    evt = wh.verify(body, {
      "svix-id": svix_id,
      "svix-timestamp": svix_timestamp,
      "svix-signature": svix_signature,
    }) as WebhookEvent;
  } catch {
    return new Response("Signature verification failed", { status: 400 });
  }
 
  if (evt.type === "user.created" || evt.type === "user.updated") {
    const { id, email_addresses, first_name, last_name, image_url } = evt.data;
    await convex.mutation(api.users.syncUser, {
      clerkId: id,
      email: email_addresses[0]?.email_address ?? "",
      name: `${first_name ?? ""} ${last_name ?? ""}`.trim(),
      imageUrl: image_url,
    });
  }
 
  return new Response("OK", { status: 200 });
}

5. File Storage

Convex includes built-in file storage, so you don't need to set up S3 or Cloudflare R2 separately.

5-1. File Upload Flow

// convex/files.ts
import { mutation, query } from "./_generated/server";
import { v } from "convex/values";
import { getCurrentUser } from "./users";
 
export const generateUploadUrl = mutation({
  handler: async (ctx) => {
    const user = await getCurrentUser(ctx);
    if (!user) throw new Error("Authentication required");
    return await ctx.storage.generateUploadUrl();
  },
});
 
export const attachToDocument = mutation({
  args: {
    documentId: v.id("documents"),
    storageId: v.id("_storage"),
  },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    if (!user) throw new Error("Authentication required");
 
    await ctx.db.patch(args.documentId, {
      storageId: args.storageId,
      updatedAt: Date.now(),
    });
  },
});
 
export const getFileUrl = query({
  args: { storageId: v.id("_storage") },
  handler: async (ctx, args) => {
    return await ctx.storage.getUrl(args.storageId);
  },
});

5-2. File Upload Component

// components/FileUpload.tsx
"use client";
 
import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";
import { useCallback, useState } from "react";
 
export function FileUpload({ documentId }: { documentId: Id<"documents"> }) {
  const [uploading, setUploading] = useState(false);
  const generateUploadUrl = useMutation(api.files.generateUploadUrl);
  const attachToDocument = useMutation(api.files.attachToDocument);
 
  const handleUpload = useCallback(
    async (e: React.ChangeEvent<HTMLInputElement>) => {
      const file = e.target.files?.[0];
      if (!file) return;
 
      setUploading(true);
      try {
        // Step 1: Get upload URL
        const uploadUrl = await generateUploadUrl();
 
        // Step 2: Upload the file
        const result = await fetch(uploadUrl, {
          method: "POST",
          headers: { "Content-Type": file.type },
          body: file,
        });
        const { storageId } = await result.json();
 
        // Step 3: Link to document
        await attachToDocument({ documentId, storageId });
      } finally {
        setUploading(false);
      }
    },
    [generateUploadUrl, attachToDocument, documentId]
  );
 
  return (
    <label className="cursor-pointer inline-flex items-center gap-2 px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700">
      {uploading ? "Uploading..." : "Attach File"}
      <input
        type="file"
        className="hidden"
        onChange={handleUpload}
        disabled={uploading}
      />
    </label>
  );
}

6. Stripe Billing Integration

6-1. Start with the version that doesn't work

Here's the shape you'll see in most Convex + Stripe write-ups: a Next.js Route Handler receives the webhook and calls a Convex mutation through ConvexHttpClient. This is what I wrote first, too.

It breaks in three places. Two of them TypeScript won't catch, and one only shows up in production. The next section takes them apart one at a time, so read this version as-is for now.

// app/api/stripe/webhook/route.ts — this does not work
import Stripe from "stripe";
import { headers } from "next/headers";
import { ConvexHttpClient } from "convex/browser";
import { api } from "@/convex/_generated/api";
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const convex = new ConvexHttpClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
 
export async function POST(req: Request) {
  const body = await req.text();
  const sig = headers().get("stripe-signature")!;
 
  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch {
    return new Response("Signature verification failed", { status: 400 });
  }
 
  switch (event.type) {
    case "checkout.session.completed": {
      const session = event.data.object as Stripe.CheckoutSession;
      const clerkId = session.metadata?.clerkId;
      if (!clerkId) break;
 
      await convex.mutation(api.subscriptions.activate, {
        clerkId,
        stripeCustomerId: session.customer as string,
        stripeSubscriptionId: session.subscription as string,
      });
      break;
    }
 
    case "customer.subscription.deleted": {
      const subscription = event.data.object as Stripe.Subscription;
      await convex.mutation(api.subscriptions.deactivate, {
        stripeSubscriptionId: subscription.id,
      });
      break;
    }
  }
 
  return new Response("OK", { status: 200 });
}

6-2. Subscription Mutations

// convex/subscriptions.ts
import { internalMutation } from "./_generated/server";
import { v } from "convex/values";
 
export const activate = internalMutation({
  args: {
    clerkId: v.string(),
    stripeCustomerId: v.string(),
    stripeSubscriptionId: v.string(),
  },
  handler: async (ctx, args) => {
    const user = await ctx.db
      .query("users")
      .withIndex("by_clerk_id", (q) => q.eq("clerkId", args.clerkId))
      .unique();
 
    if (!user) throw new Error("User not found");
 
    await ctx.db.patch(user._id, {
      plan: "pro",
      stripeCustomerId: args.stripeCustomerId,
      stripeSubscriptionId: args.stripeSubscriptionId,
    });
  },
});
 
export const deactivate = internalMutation({
  args: { stripeSubscriptionId: v.string() },
  handler: async (ctx, args) => {
    const user = await ctx.db
      .query("users")
      .filter((q) =>
        q.eq(q.field("stripeSubscriptionId"), args.stripeSubscriptionId)
      )
      .unique();
 
    if (!user) return;
 
    await ctx.db.patch(user._id, {
      plan: "free",
      stripeSubscriptionId: undefined,
    });
  },
});

Three reasons the webhook kept returning 500

Push the previous section's code to production and your Stripe dashboard's webhook log fills with 500s. Running stripe listen locally gives you the same thing. There are three causes, and they fail in three different ways.

Reason 1: `internalMutation` can't be called from a client

In 6-2 we defined activate and deactivate as internalMutation. Then in 6-1 we called one of them from ConvexHttpClient as api.subscriptions.activate. That combination can't work.

The Convex docs are explicit: "Internal functions can only be called by other functions and cannot be called directly from a Convex client." Internal functions live on the internal object in _generated/api, not on api, and only other Convex functions can reach them — via ctx.runMutation or the scheduler.

That leaves two ways forward.

Option	What it means	Trade-off
A. Make it a public mutation	Change `internalMutation` to `mutation`, add a shared secret argument, and verify it yourself	Quick, but it puts a function that rewrites billing state on your public surface. Forget the secret check once and anyone can promote themselves to Pro
B. Receive the webhook in a Convex HTTP Action	Verify the Stripe signature inside Convex, then call `ctx.runMutation(internal.…)`	Internal functions stay internal, and no billing relay code lingers in your Next.js app

I went with B. Option A stakes your security on remembering to write a check — and billing functions are the last place I want that kind of promise. If a function can stay off the public surface, it should.

Reason 2: `Stripe.CheckoutSession` isn't a real type

event.data.object as Stripe.CheckoutSession doesn't exist in the stripe package's type definitions. The correct name has an extra namespace: Stripe.Checkout.Session. Since the subscription branch really is Stripe.Subscription, having only one of the two wrong is easy to miss.

// Wrong
const session = event.data.object as Stripe.CheckoutSession;
 
// Right
const session = event.data.object as Stripe.Checkout.Session;

Reason 3: `headers()` returns a Promise in Next.js 15 and later

headers().get("stripe-signature") is Next.js 14 syntax. In Next.js 15, headers, cookies, and draftMode became asynchronous and now return promises. Synchronous access still works for the moment for compatibility, but it warns in both development and production. One await fixes it.

const sig = (await headers()).get("stripe-signature")!;

If you're migrating a larger codebase, npx @next/codemod@canary next-async-request-api rewrites these call sites for you.

The fixed version: move it into `convex/http.ts`

Fixing all three moves the webhook endpoint into Convex itself. Convex registers routes on an httpRouter in convex/http.ts and defines handlers with httpAction. Inside an httpAction you get ctx.runMutation, ctx.runQuery, and ctx.runAction — so internal functions are callable directly.

// convex/http.ts
import { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";
import { internal } from "./_generated/api";
import Stripe from "stripe";
 
const http = httpRouter();
 
http.route({
  path: "/stripe/webhook",
  method: "POST",
  handler: httpAction(async (ctx, request) => {
    const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
    const body = await request.text();
    const sig = request.headers.get("stripe-signature");
    if (!sig) return new Response("Missing signature", { status: 400 });
 
    let event: Stripe.Event;
    try {
      // Use the async variant on Workers-style runtimes
      event = await stripe.webhooks.constructEventAsync(
        body,
        sig,
        process.env.STRIPE_WEBHOOK_SECRET!
      );
    } catch {
      return new Response("Signature verification failed", { status: 400 });
    }
 
    switch (event.type) {
      case "checkout.session.completed": {
        const session = event.data.object as Stripe.Checkout.Session;
        const clerkId = session.metadata?.clerkId;
        if (!clerkId) break;
 
        await ctx.runMutation(internal.subscriptions.activate, {
          clerkId,
          stripeCustomerId: session.customer as string,
          stripeSubscriptionId: session.subscription as string,
        });
        break;
      }
 
      case "customer.subscription.deleted": {
        const subscription = event.data.object as Stripe.Subscription;
        await ctx.runMutation(internal.subscriptions.deactivate, {
          stripeSubscriptionId: subscription.id,
        });
        break;
      }
    }
 
    // Anything other than a 200 and Stripe keeps retrying
    return new Response(null, { status: 200 });
  }),
});
 
export default http;

One note on constructEventAsync. Convex HTTP Actions, like Cloudflare Workers, don't run the Node.js crypto module that the synchronous signature check depends on. Leave constructEvent in place and you get the most time-consuming failure mode there is: a correct signature that fails verification anyway.

The other easy one to miss is the endpoint URL you register in the Stripe dashboard. Convex serves HTTP Actions from .convex.site, not .convex.cloud.

https://<your-deployment>.convex.site/stripe/webhook

Register the convex.cloud host and you get a 404, and Stripe will only tell you the endpoint doesn't exist. That one cost me about an hour.

The internalMutation definitions in 6-2 stay exactly as they are. The real change in this section is that they're reached through internal instead of api — and that app/api/stripe/webhook/route.ts can be deleted.

7. Debugging and Refactoring with Antigravity

7-1. Common Errors Antigravity Helps You Fix

Error 1: Convex query argument type mismatch

Type 'string' is not assignable to type 'Id<"workspaces">'

Paste this into Antigravity's chat and ask it to fix the error. It'll immediately suggest:

// Before
const docs = useQuery(api.documents.listByWorkspace, {
  workspaceId: params.id,  // string type — wrong
});
 
// After
import { Id } from "@/convex/_generated/dataModel";
 
const docs = useQuery(api.documents.listByWorkspace, {
  workspaceId: params.id as Id<"workspaces">,  // correct
});

Error 2: Calling external APIs from Convex queries

Convex queries and mutations can't call external APIs directly. Use action instead:

// convex/ai.ts
import { action } from "./_generated/server";
import { v } from "convex/values";
 
export const summarizeDocument = action({
  args: { content: v.string() },
  handler: async (ctx, args) => {
    // Actions can call external APIs
    const response = await fetch("https://api.example.com/summarize", {
      method: "POST",
      body: JSON.stringify({ text: args.content }),
    });
    const data = await response.json();
    return data.summary;
  },
});

7-2. Automated Code Review with Antigravity

After writing any significant chunk of code, ask Antigravity: "Please review this code for security vulnerabilities and performance issues." You'll get actionable feedback like:

Missing permission checks in Convex mutations
Using collect() where paginate() should be used for large datasets
Queries that aren't using indexes properly

This kind of AI-assisted code review catches production-level bugs before they ever ship.

8. Deploying to Cloudflare Pages

8-1. Configuration

pnpm add -D @cloudflare/next-on-pages

Create wrangler.toml:

name = "collabdocs"
compatibility_date = "2024-01-01"
compatibility_flags = ["nodejs_compat"]
 
[build]
command = "pnpm run build"

Add to package.json:

{
  "scripts": {
    "pages:build": "npx @cloudflare/next-on-pages",
    "deploy": "pnpm pages:build && wrangler pages deploy .vercel/output/static"
  }
}

8-2. Environment Variables

Set these in your Cloudflare Pages dashboard:

NEXT_PUBLIC_CONVEX_URL — Your Convex deployment URL
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY — Clerk publishable key
CLERK_SECRET_KEY — Clerk secret key
CLERK_WEBHOOK_SECRET — Clerk webhook signing secret
STRIPE_SECRET_KEY — Stripe secret key
STRIPE_WEBHOOK_SECRET — Stripe webhook signing secret
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY — Stripe publishable key

8-3. Deploy Convex to Production

npx convex deploy

This deploys your Convex functions and schema to the production environment and gives you a production URL to set in Cloudflare.

9. Enforcing Plan Limits

Gating features by plan creates a natural upgrade path for your users.

// convex/workspaces.ts
export const create = mutation({
  args: { name: v.string() },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    if (!user) throw new Error("Authentication required");
 
    // Enforce Free plan limits
    if (user.plan === "free") {
      const existingWorkspaces = await ctx.db
        .query("workspaces")
        .withIndex("by_owner", (q) => q.eq("ownerId", user._id))
        .collect();
 
      if (existingWorkspaces.length >= 3) {
        throw new Error(
          "Free plan is limited to 3 workspaces. Upgrade to Pro to create more."
        );
      }
    }
 
    const now = Date.now();
    return await ctx.db.insert("workspaces", {
      name: args.name,
      ownerId: user._id,
      plan: user.plan,
      memberIds: [user._id],
      createdAt: now,
      updatedAt: now,
    });
  },
});

Notes from building this solo

The steps above are the clean version. Here's what it actually felt like to run this alone.

Antigravity earned its keep somewhere other than writing code. It was the loop after a schema change — reconnecting every caller that just broke. Adding archivedAt to the documents table produced type errors in eleven places across queries, mutations, and React components. Handing the Agent "follow this schema change through" fixed nine of them in one pass. The two it left were the ones where I hadn't decided whether archived documents belonged in that view at all. What remained on my desk was exactly the part that needed a judgment call.

There was also a place where Convex was the wrong choice. I tried to put roughly 300,000 event-log rows in it for analytics. Convex is built around per-document subscriptions, which is a poor fit for scanning large row counts in aggregate. collect() ran into execution limits, and I ended up moving that slice out to a separate analytics store. The mistake was treating "collaborative editing state" and "an append-only log" as the same kind of data.

On billing, I should have spent the time on observability rather than implementation. Each of the three webhook failures takes about five minutes to fix. What consumed the day was not knowing which one I was looking at. Opening convex logs and firing stripe trigger checkout.session.completed against it — as the first step, not the last — would have saved most of that. Building a local reproduction before the code works is obvious advice that I skipped once things started moving.

And plan limits are cheaper to add on day one. The existingWorkspaces.length >= 3 check in section 9 looks like something to defer, but retrofitting it turns into a migration question: what do you do with the user who already has four? Put it in alongside the initial schema.

Wrapping up

What Convex and Antigravity actually shortened wasn't the real-time sync implementation so much as the cost of changing your mind about the design. When a schema stops feeling like something you're locked into, you stop needing to get it perfect on the first pass.

Billing was the exception — the one area where AI assistance didn't help much. Calling an internalMutation through api, mixing up .convex.site and .convex.cloud: both of those read as correct code. That part still comes down to spending real time in the documentation.

If you're picking this up, start with a single convex/http.ts and get stripe trigger checkout.session.completed passing locally before you build out the app. Having that one wire connected first changes how the rest of the project goes.

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.