Skip to main content

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:

bash
pnpm exec convex deploy

It 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:

.env.local
CONVEX_DEPLOY_KEY=prod:your-deployment|your-key

Create 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:

  1. Set SITE_URL, BETTER_AUTH_SECRETS, and BCN_AUTH_PROXY_IP_SECRET in Convex, as described in environment variables. Convex sets its CONVEX_SITE_URL built-in itself.

    A deployment with a SITE_URL that is not localhost and no email hook fails to load when the app sends auth mail (emailOTP, password verification or reset, organization invitations), and the previous version keeps running. Add the email hook to convex/auth.ts before you deploy. See Transactional auth email.

  2. 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.
  3. 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.

  4. Before you announce the release, open https://app.example.com/api/auth/jwks and check that it lists the returned kid.
  5. For MCP, create the host OAuth clients with auth.oauthOperator. See Delegated OAuth and MCP.
  6. 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 --noEmit in CI next to the Nuxt type check. convex deploy type-checks every file in convex/ with convex/tsconfig.json, tests included. Without this check, a type error that only convex deploy finds stops the production release.
  • Set an exact HTTPS SITE_URL without a path, and pass the same value as convex.auth.origin.
  • Keep BETTER_AUTH_SECRETS out of Nuxt. Keep BCN_AUTH_PROXY_IP_SECRET out of public config and logs.
  • Set NUXT_PUBLIC_CONVEX_SITE_URL to the exact HTTP Actions origin. Do not try to override the CONVEX_SITE_URL built-in in Convex.
  • Check that /api/auth/* reaches the intended .convex.site origin.
  • Allow the exact Convex HTTPS and WebSocket origins in your Content Security Policy.
  • Set convex.auth.trustedClientIpHeader to 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.