Environment Variables

Configure Convex, Nuxt, and Better Auth without mixing build-time and runtime concerns.

Better Convex Nuxt connects three environments: the Nuxt build, the deployed Nuxt server and browser, and the Convex deployment. Put each value in the environment that consumes it.

Nuxt variables

Variable	Required	Purpose
`NUXT_PUBLIC_CONVEX_URL`	Yes	Public Convex deployment URL, usually ending in `.convex.cloud`
`NUXT_PUBLIC_CONVEX_SITE_URL`	With auth for local or custom domains	Convex HTTP Actions origin used by the same-origin auth proxy

The module also reads CONVEX_URL and CONVEX_SITE_URL while Nuxt config is evaluated. Prefer the NUXT_PUBLIC_* names in deployment environments: Nuxt can apply those native public runtime-config overrides after the image was built.

.env

NUXT_PUBLIC_CONVEX_URL=https://example.convex.cloud
NUXT_PUBLIC_CONVEX_SITE_URL=https://example.convex.site

These values are public endpoints, not secrets. Do not place secrets in runtimeConfig.public.

Convex variables for authentication

Set these on the Convex deployment, not in the browser bundle:

Variable	Required with auth	Purpose
`SITE_URL`	Yes	Exact public Nuxt origin used as the Better Auth base and trusted origin
`BETTER_AUTH_SECRET`	Yes	Random signing secret with at least 32 characters

bash

pnpm exec convex env set SITE_URL https://app.example.com
pnpm exec convex env set BETTER_AUTH_SECRET "$(openssl rand -base64 32)"

SITE_URL must be an origin only: no path, query, or fragment. Use HTTPS outside loopback development. Configure separate values for preview and production deployments.

Build-time versus deploy-time

CONVEX_URL is read when nuxt.config.ts runs. If a platform builds once and promotes the same artifact between environments, a later CONVEX_URL does not replace the baked public config. Use NUXT_PUBLIC_CONVEX_URL and NUXT_PUBLIC_CONVEX_SITE_URL as native deploy-time overrides, or rebuild for each environment.

Auth identity is also environment-specific. A preview Nuxt origin must point to a Convex deployment whose SITE_URL matches that preview exactly. Do not share production cookies, secrets, or Convex data with previews.

Verify before deployment

Check all four boundaries:

The browser can reach NUXT_PUBLIC_CONVEX_URL.
The Nuxt server can reach both Convex origins.
Convex has the exact public Nuxt origin in SITE_URL.
BETTER_AUTH_SECRET exists only in the Convex environment and secret management system.

Continue with Deployment for the complete release checklist.

Report an issue