Deployment
Deploy a Nuxt and Convex application in the right order, with working SSR, realtime, and authentication.
Deploy Convex and Nuxt as two services. Convex runs the database and your functions. Nuxt renders pages, serves the browser bundle, runs server routes, and runs the auth proxy.
For a step-by-step guide on one host, see Deploy to Vercel.
What you need
- a Convex production deployment;
- a Nuxt host that runs the Nitro server;
- one public HTTPS origin for the Nuxt application;
- browser access to the Convex HTTPS and WebSocket endpoints.
Authentication needs the /api/auth/* Nitro route, so a static host without
a server cannot run it. An application without convex.auth can use Nuxt's
static output, but test its SSR and client navigation first.
Deploy Convex before the frontend
Deploy Convex in the same release pipeline as the frontend, before the frontend build. Then a failed Convex deploy stops the release, and the frontend never goes live before the Convex functions that it calls.
On CI or a host, run the plain Convex CLI:
pnpm exec convex deployIt reads CONVEX_DEPLOY_KEY from the environment. Use a deploy-only key: a
production deploy key with only the deployment:deploy permission. Add it
only to the production environment of the host. For a complete build script,
see Deploy to Vercel.
The new Convex functions go live before the new frontend. Until it does, open tabs and the previous frontend call the new functions. If the frontend build fails after the Convex deploy, the previous frontend stays live. Keep each Convex change compatible with the previous frontend: add a function or an optional argument first, and remove the old one in a later release.
Select the production deployment
Convex commands that you run in a terminal use pnpm exec better-convex-nuxt convex.
This wrapper reads the target deployment only from .env.local in the current
folder. It ignores CONVEX_* variables from the shell and rejects target
flags such as --prod. Use the plain Convex CLI only in the release pipeline.
For production, run the commands from a separate checkout of your repository
with its dependencies installed. Its .env.local contains only a key for
admin tasks. This is a production deploy key that can set environment
variables and run functions:
CONVEX_DEPLOY_KEY=prod:your-deployment|your-keyCreate the key in the Convex dashboard, under the production deployment's
settings. A deploy-only key cannot set environment variables or run
functions. deploy refuses a development key and a plain CONVEX_DEPLOYMENT
name. Check the file before every production command. Never commit it.
Deployment order
For the first launch, do these steps in this order:
Set
SITE_URL,BETTER_AUTH_SECRETS, andBCN_AUTH_PROXY_IP_SECRETin Convex, as described in environment variables. Convex sets itsCONVEX_SITE_URLbuilt-in itself.A deployment with a
SITE_URLthat is notlocalhostand noemailhook fails to load when the app sends auth mail (emailOTP, password verification or reset, organization invitations), and the previous version keeps running. Add theemailhook toconvex/auth.tsbefore you deploy. See Transactional auth email.- Run the release pipeline. It deploys the Convex schema, functions, HTTP routes, and auth component, and then builds and deploys Nuxt with its environment variables.
Create the signing key once, before the first user signs in:
bash pnpm exec better-convex-nuxt convex run auth:ensureSigningKey '{}'The action returns
{ created, kid }. Running it again returns the same key.- Before you announce the release, open
https://app.example.com/api/auth/jwksand check that it lists the returnedkid. - For MCP, create the host OAuth clients with
auth.oauthOperator. See Delegated OAuth and MCP. - Test sign-in on the deployed origin, then open the application to users.
Later releases only run the pipeline.
Retired signing keys stay published for 21 minutes after a rotation. Schedule
the internal auth:pruneSigningKeys mutation, for example as a daily Convex
cron, to delete keys after that time. It deletes at most batchSize keys per
call (1 to 256, default 64) and never the current key. Run it again while it
returns hasMore: true.
Production checklist
- Install the exact Better Auth and OAuth provider versions from the package manifest. See release compatibility.
- Run
tsc -p convex --noEmitin CI next to the Nuxt type check.convex deploytype-checks every file inconvex/withconvex/tsconfig.json, tests included. Without this check, a type error that onlyconvex deployfinds stops the production release. - Set an exact HTTPS
SITE_URLwithout a path, and pass the same value asconvex.auth.origin. - Keep
BETTER_AUTH_SECRETSout of Nuxt. KeepBCN_AUTH_PROXY_IP_SECRETout of public config and logs. - Set
NUXT_PUBLIC_CONVEX_SITE_URLto the exact HTTP Actions origin. Do not try to override theCONVEX_SITE_URLbuilt-in in Convex. - Check that
/api/auth/*reaches the intended.convex.siteorigin. - Allow the exact Convex HTTPS and WebSocket origins in your Content Security Policy.
- Set
convex.auth.trustedClientIpHeaderto a header that your host overwrites with one client IP. A missing or invalid value stops auth requests. - Make sure public traffic can reach the Nuxt server only through that host. Otherwise a client can send the header itself.
- Keep module logging off unless you investigate a specific problem.
- Test sign-in, sign-out, SSR refresh, client navigation, and realtime reconnect.
- Test your Convex access checks with two different users, not only the UI.
- Test each social provider's callback, and the error page for an existing account.
- For MCP, also test consent, PKCE, a wrong client, resource, or scope, revocation, and removing a membership.
Do not let the first sign-in create the signing key, and never delete JWKS rows by hand.
Preview deployments
Better Auth accepts requests only from the exact SITE_URL. A preview with a
random URL therefore cannot sign users in against the production deployment.
Give a stable preview its own Convex deployment, exact SITE_URL, and its own
secrets. Do not share production secrets, cookies, or data with previews, and
do not use wildcard trusted origins. Never give a preview build a production
deploy key. A preview build runs the code of any branch.
Health checks
A successful HTML response proves only that Nuxt started. Also check:
- an anonymous Convex query;
- a server-rendered page for a signed-in user, when auth is on;
- a browser subscription that receives a change;
- that the auth proxy rejects unsupported methods.
Read the security model before you open the application to the public.