Vercel
Deploying the app to Vercel, with the backend staying on Convex, and the four settings that have to be right.
Vercel is the shortest path from this folder to an address, because the app is a Next.js app and that is what Vercel builds. The backend does not move: it stays on Convex, and the app is pointed at the production deployment rather than at the one on your laptop.
Before you start
The folder in a repository
Vercel deploys from Git, so the folder has to be somewhere it can read. Push it to GitHub, GitLab or
Bitbucket, with node_modules and .env.local left behind as .gitignore already says.
A production deployment on Convex
npx convex deployThen set the twelve deployment names on it, with --prod on every one of them. The full list is
Deployment names; the four that stop the site working are
BETTER_AUTH_SECRET, SITE_URL, and the mail pair if you want confirmation emails to arrive.
The address you are going to have
Vercel gives a project a .vercel.app address, and it also takes a domain of your own. Decide which one
people will visit before you create the project, because three separate things have to agree on it:
NEXT_PUBLIC_APP_URL, SITE_URL, and the callback addresses in Google's and GitHub's consoles.
The project
Import the repository
New project, pick the repository, and leave the framework preset on Next.js. Vercel reads the build
command from package.json, which is already next build.
The app's own settings
These go in the project's environment variables, for all environments. They are the seven from App names:
| Name | Value |
|---|---|
NEXT_PUBLIC_CONVEX_URL | The production deployment's address, ending .convex.cloud |
NEXT_PUBLIC_APP_URL | https://your-app-address |
SETTINGS_SECRET | Your own long random string, not the one from your laptop |
GITHUB_CONNECT_CLIENT_ID | Optional. The connect application, if you want push to GitHub |
GITHUB_CONNECT_CLIENT_SECRET | The other half of that pair |
ALLOW_SELF_UPDATE | Leave unset. A platform has no folder for the panel to update |
Push the backend on every deploy, if you want it automatic
Convex documents a build command for exactly this, which deploys the functions and then builds the app:
npx convex deploy --cmd 'pnpm build'It needs CONVEX_DEPLOY_KEY in the project's environment, which is a production deploy key from the
Convex dashboard. Set the command in the project's build settings and the backend stops being a step
you have to remember.
Without it, nothing breaks: npx convex deploy from your machine is the same deploy, done by hand.
Deploy, then finish the pair that has to match
The first deploy tells you the address. Put it in NEXT_PUBLIC_APP_URL here and in SITE_URL on the
deployment, then add it to the callback lists in
Google and GitHub. A provider
that has not been told about the new address refuses the sign-in with a message naming the address it
received.
What works as it is, and what does not
| Piece | On Vercel |
|---|---|
| The product, chat and all | Works. The API routes run on Node and stream normally |
The documentation, /docs | Works, and it is baked at build time: the .mdx addresses are static files |
| Uploads and pictures | Works: files are stored by the deployment, not by the app |
| Sign in, including Google and GitHub | Works, once the callbacks name the new address |
| Scheduled work | Unaffected. It runs on the deployment, not on the app |
System → Setup & licensing update button | Does nothing here, and it says so. There is no folder to run git in |
Three things that catch people out
A long turn that is cut off is the platform's function timeout rather than the product's. Raise the duration limit for the project in its settings.
SETTINGS_SECRET copied from the laptop is fine only if both point at the same deployment. A
production installation wants its own, decided once, because every sealed token is encrypted with it and
changing it later means reconnecting everything.
SITE_URL still saying localhost is the classic half-finished deploy: sign-in by password works, and
every link in every email points at a machine in your house.
Afterwards
Open System → Status & health on the deployed address and confirm the four
checks.
Brand → Emails, and read it on a phone.Create a second account and go through onboarding, which is what your users do first.
Read Updating: a platform deploy is the update, and the snapshot is still yours to take.