Skip to main content
By default, every Botflow project comes with Convex as its backend (you can also create a frontend-only project with no backend). Convex gives your app a typed database, reactive queries, serverless functions, scheduled jobs, and file storage — all defined in TypeScript alongside your frontend code.

​
What Convex gives you

  • Real-time database — a document store where data changes stream to connected clients the moment they happen. No polling, no manual cache invalidation.
  • Typed queries and mutations — reads and writes are TypeScript functions (query, mutation). Call them from React with useQuery and useMutation.
  • Actions — async server-side functions that can call external APIs, send emails, or do anything you can’t do in a pure query.
  • HTTP endpoints — expose individual functions as REST endpoints for webhooks and third-party integrations.
  • Scheduled jobs — run a function on a recurring cron schedule or delay it to a specific time.
  • File storage — upload, store, and serve files through the same TypeScript API.

​
Projects without a backend

Not every app needs a database. When you create a project you can choose No Backend — a frontend-only app (a landing page, a marketing site, a calculator, a client-side tool) with no Convex deployment at all. In a frontend-only project:
  • There’s no convex/ folder and no Database tab.
  • Features that depend on the backend — Authentication, Payments, and the data tools above — aren’t available.
  • The agent won’t pull in Convex packages, so the app stays lean and purely client-side.
Choose it when you know you only need a static or client-side app. If you later need user accounts, saved data, or payments, start a project with a Convex backend.

​
Accessing the database in the workspace

Click the Database tab at the top of the workspace to open the embedded Convex dashboard. From here you can:
  • Browse tables — see all documents in every table, paginated
  • Run queries — call any query or mutation function with custom arguments
  • Inspect logs — view real-time function execution logs
  • Manage scheduled jobs — see pending and past cron jobs
  • View the schema — inspect the current schema.ts definition
The Database tab shows the real Convex dashboard embedded in an iframe. Any changes you make here are immediately reflected in your live app.

​
How Convex is wired up per plan

PlanWhat you get
FreeBring your own Convex account. Connect it in Settings → Connections and Botflow injects VITE_CONVEX_URL automatically.
ProA platform-managed Convex deployment per project. No setup needed — just build.
MaxSame as Pro, with higher function limits and priority support.

​
Connecting your own Convex (Free plan)

  1. Go to dashboard.convex.dev and create a free Convex account.
  2. Create a new deployment in the Convex dashboard.
  3. In Botflow, go to Settings → Connections and click Connect Convex.
  4. Paste your Convex deployment URL.
Botflow will inject the URL as an environment variable (VITE_CONVEX_URL). The AI agent automatically uses this variable when generating Convex client code.
After connecting Convex, the Database tab becomes available in your workspace. See Workspace → Database for details on using the Convex dashboard.

​
Editing data through the agent

Beyond writing functions, the AI agent can work with your database directly — handy for seeding sample data, debugging, or one-off fixes without building a UI for them. Just ask: 
Seed the products table with 5 realistic example rows

Show me the 10 most recent orders

Delete the test user with email demo@example.com
Under the hood the agent can list your tables, read documents (with pagination), and insert, update, or delete rows. It also reads your function execution logs, so you can ask it to “check why the createOrder mutation is failing” and it will look at the real error output.
Direct writes change live data immediately. The agent will confirm before destructive changes, but treat it like running SQL by hand — double-check before seeding or deleting against data you care about.

​
Writing Convex code

Convex schema, queries, mutations, and actions live in the convex/ directory of your project. The AI agent writes and edits these files like any other source file. A typical Convex file structure: 
convex/
  schema.ts       # Table definitions with validators
  tasks.ts        # Queries and mutations for the tasks table
  auth.config.ts  # Auth configuration (if you've added authentication)
  _generated/     # Auto-generated API types (don't edit)
Example convex/tasks.ts: 
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";

export const list = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query("tasks").order("desc").collect();
  },
});

export const create = mutation({
  args: { text: v.string() },
  handler: async (ctx, args) => {
    return await ctx.db.insert("tasks", { text: args.text, completed: false });
  },
});
Call these from your React component: 
import { useQuery, useMutation } from "convex/react";
import { api } from "../convex/_generated/api";

export function TaskList() {
  const tasks = useQuery(api.tasks.list);
  const create = useMutation(api.tasks.create);
  // ...
}

​
Prompting the AI to use Convex

The agent understands Convex and will use it automatically in any project with a Convex backend. You can be explicit: 
Add a Convex mutation that marks a task as complete. Update the task list component to call it when the checkbox is clicked.

Add a scheduled job that sends a daily digest email via Resend at 9am UTC

Create a Convex HTTP endpoint at /api/webhook/stripe that processes payment events