Convex
Creating the deployment, the difference between a development one and a production one, and the address the app needs.
Convex is the database, the functions, the accounts and the scheduled work. It is the one dependency that is not optional, and it is also the one where the setup is a single command.
Creating it
An account
convex.dev, free to start. The free tier is enough to run this product while you set it up, and the tier you end on depends on traffic rather than on features: nothing in this installation is held back behind a paid plan on Convex's side.
The development deployment
npx convex devThe first run asks you to sign in through the browser, then asks whether to create a new project or use an
existing one. Choose new, give it a name, and it creates a development deployment, pushes the schema and
the functions, writes NEXT_PUBLIC_CONVEX_URL into .env.local, and stays running to watch for changes.
The address
The command prints two addresses, and the difference between them matters later:
| Address | Example | What it serves |
|---|---|---|
| The deployment URL | https://quick-fox-1234.convex.cloud | Queries and mutations, the app's data path |
| The site URL | https://quick-fox-1234.convex.site | HTTP routes, which is where /api/auth lives |
The first administrator
npx convex env set ADMIN_EMAIL "you@your-domain.com"
npx convex env set ADMIN_PASSWORD "a long one"
npx convex run admin:bootstrapThe app
pnpm devWith NEXT_PUBLIC_CONVEX_URL in place, the app serves. A blank page for a few seconds while the first
compile finishes is normal.
Development and production are two places
This is the part worth reading twice. A development deployment and a production deployment are separate databases with separate environments and separate addresses. Trying a change against development and then pushing it to production is the intended workflow, and it is safe because production is not touched until you say so.
npx convex dev # watch and push to development
npx convex deploy # push schema and functions to production
npx convex env set N v --prod # set a production name
npx convex env list --prod # check which names production hasnpx convex deploy needs a production deployment to have been created once in the Convex dashboard, under the
same project. After that, the command is the whole deployment story on the backend side: there is no build
step, no container and no server to restart.
The environment is not shared, and the data is not either
A name set on development does not exist on production, and a row written on
production does not appear on development. So npx convex env set ADMIN_EMAIL ... without --prod configures the copy you are testing, not the one your
users are on. This is the most common cause of "it works locally".
What the deployment holds
| Area | Examples |
|---|---|
| Schema | Accounts, sessions, projects, files, threads, messages, credits, plans, settings |
| Queries and mutations | Everything the app reads and writes through the Convex client |
| Actions | Calls to other people's APIs: models, mail, payments, Git providers, MCP servers |
| HTTP routes | The authentication routes, at /api/auth on the site URL |
| Scheduled functions | Credit windows, retention, health pings, reminder mail |
| Migrations | Bringing an older schema forward, run deliberately rather than on deploy |
| Environment | The twelve names on the deployment page |
Nothing runs on your machine except the app. There is no worker to keep alive, no queue to drain and no cron of yours to configure: the scheduled work is a function of the deployment.
The commands you will actually use
| Command | When |
|---|---|
npx convex dev | While you are changing anything under convex/ |
npx convex dev --once | Once, and exit, for a script or a check |
npx convex deploy | Releasing schema and functions to production |
npx convex env set NAME value | Setting one name on development |
npx convex env set NAME value --prod | Setting one name on production |
npx convex run admin:bootstrap | Creating the first administrator |
npx convex dashboard | Opening the dashboard for this project |
npx convex logs | Watching the deployment's log, which is where an action's failure shows up |
Reset the wrong deployment and you lose what is in it
The dashboard offers to clear a deployment's tables. Development is a fine
place to do that. Production is not, and the panel's System → Backups & exports exists so that a snapshot is taken before anybody is tempted.