Deployment

Deploy Convex and Nuxt as two coordinated services. Convex owns the database and functions. Nuxt owns rendering, browser delivery, server routes, and the same-origin auth proxy.

Choose a supported topology

The normal topology is:

• a Convex cloud deployment;
• a Nuxt deployment with Nitro server support;
• one public HTTPS origin for the Nuxt application;
• browser access to Convex HTTPS and WebSocket endpoints.

Authentication requires the generated /api/auth/* Nitro route. A fully static host without Nitro is not a supported auth topology. An app with auth: false can use Nuxt's static output, but only after its own SSR and client-navigation behavior is verified.

Deployment order

1. Deploy the Convex schema, functions, HTTP routes, and auth component.
2. Set the Convex SITE_URL and BETTER_AUTH_SECRET variables.
3. Build and deploy Nuxt with the public Convex URLs.
4. Verify the deployed origins and auth ceremony.

pnpm exec convex deploy
pnpm build

Use your platform's standard commands when they wrap these steps. The important invariant is that the Nuxt build targets the intended Convex deployment.

Production checklist

• Use a supported Node, Nuxt, Convex, Better Auth, and adapter version tuple.
• Set an exact HTTPS SITE_URL without a trailing path.
• Keep BETTER_AUTH_SECRET out of Nuxt public config and logs.
• Confirm /api/auth/* reaches the intended .convex.site origin.
• Permit the exact Convex HTTPS and WebSocket origins in Content Security Policy.
• Make the ingress overwrite any header configured as trustedClientIpHeader.
• Keep module logging off unless investigating a specific problem.
• Exercise sign-in, sign-out, SSR refresh, client navigation, and realtime reconnect.
• Verify backend authorization with two different users, not only UI visibility.
• Rehearse OAuth callbacks, recovery, expiry, denial, and rollback for every enabled provider.

Preview deployments

An arbitrary preview URL cannot safely reuse production auth configuration. Give stable previews their own Convex deployment and exact SITE_URL, or disable auth for documentation-style previews. Wildcard trusted origins and shared production secrets weaken the boundary and are not a substitute for isolated environments.

Health checks

A successful HTML response proves only that Nuxt started. Add checks that cover the actual dependency chain:

• an anonymous Convex query;
• an authenticated server-rendered page when auth is enabled;
• a browser subscription receiving a change;
• the auth proxy rejecting unsupported methods and invalid upstream behavior.

See Security Model before exposing the application publicly.