Environment Variables
Configure environment variables and services for the Nuxt template.
The template configures every service through Nuxt's runtimeConfig. This page
maps each environment variable to what it does and whether it is required.
How runtime config works
Environment variables are declared in the runtimeConfig block of
nuxt.config.ts and populated by convention:
NUXT_*populates server-only keys (e.g.NUXT_BETTER_AUTH_SECRET→runtimeConfig.betterAuthSecret). These are never sent to the browser.NUXT_PUBLIC_*populatesruntimeConfig.publicand is exposed to the client (e.g.NUXT_PUBLIC_BASE_URL→runtimeConfig.public.baseUrl).
Read them on the server (or in app.config-style code) with
useRuntimeConfig(). A few public keys read process.env directly with a
default in nuxt.config.ts — the Creem product IDs and the AI demo toggle — so
they resolve even when not set.
Only put values you are comfortable shipping to the browser under
NUXT_PUBLIC_*. Secrets (auth secret, API keys, webhook secrets) must stay on
the server-only keys.
Each variable below is marked:
- Required — the app needs it to boot.
- Feature — only needed to enable a specific feature.
- Optional — has a sensible default or is rarely changed.
App
| Variable | Scope | Required | Description |
|---|---|---|---|
NUXT_PUBLIC_BASE_URL | public | Required | Base URL of the app; drives Better Auth baseURL/trustedOrigins and payment redirect URLs. http://localhost:3000 locally. |
NUXT_PUBLIC_AI_PUBLIC_DEMO | public | Optional | When "true", AI chat/media routes allow anonymous access (hosted demo). Leave unset/false to require login. |
Better Auth
| Variable | Scope | Required | Description |
|---|---|---|---|
NUXT_BETTER_AUTH_SECRET | server | Required | Secret used to sign sessions. Generate with openssl rand -base64 32. |
NUXT_AUTH_EXTRA_TRUSTED_ORIGINS | server | Optional | Comma-separated extra trusted origins (e.g. LAN testing). Read directly from process.env in server/utils/auth.ts. |
Database
| Variable | Scope | Required | Description |
|---|---|---|---|
NUXT_DATABASE_URL | server | Required | PostgreSQL connection string used by Drizzle and Drizzle Kit. |
NUXT_ORM_PROVIDER | server | Optional | Reserved for future ORM options; only drizzle is implemented. |
Email (Resend)
| Variable | Scope | Required | Description |
|---|---|---|---|
NUXT_RESEND_API_KEY | server | Feature | Resend API key. Required for verification, password-reset, and contact emails. Without it, email verification blocks login. |
See Email for sender/support addresses and templates.
OAuth providers
All four are Feature variables — set a provider's pair to enable its login button; leave them unset (and hide the button) otherwise.
| Variable | Scope | Description |
|---|---|---|
NUXT_GITHUB_CLIENT_ID | server | GitHub OAuth client ID. |
NUXT_GITHUB_CLIENT_SECRET | server | GitHub OAuth client secret. |
NUXT_GOOGLE_CLIENT_ID | server | Google OAuth client ID. |
NUXT_GOOGLE_CLIENT_SECRET | server | Google OAuth client secret. |
See Authentication for callback URLs.
Payments — ZPay
ZPay is the default payment provider; it is only registered when its URL, merchant ID, and merchant key are all set.
| Variable | Scope | Description |
|---|---|---|
NUXT_ZPAY_URL | server | ZPay gateway endpoint (e.g. https://zpayz.cn/mapi.php). |
NUXT_ZPAY_MERCH_ID | server | Merchant ID. |
NUXT_ZPAY_MERCH_KEY | server | Merchant key, used to sign requests and verify callbacks. |
NUXT_ZPAY_NOTIFY_URL | server | Public callback URL for ZPay notifications. |
Payments — Creem
Creem is registered when NUXT_CREEM_API_KEY is set. The product IDs map to the
plans in app/config/price-config.ts (Free / Pro monthly+yearly / Lifetime).
| Variable | Scope | Description |
|---|---|---|
NUXT_CREEM_SERVER_IDX | server | Server index: 0 = production, 1 = test. |
NUXT_CREEM_API_KEY | server | Creem API key. |
NUXT_CREEM_WEBHOOK_SECRET | server | Secret used to verify the creem-signature on webhooks. |
NUXT_CREEM_NOTIFY_URL | server | Public callback URL for Creem notifications. |
NUXT_PUBLIC_CREEM_PRODUCT_PRO_MONTHLY | public | Creem product ID for the Pro monthly plan. |
NUXT_PUBLIC_CREEM_PRODUCT_PRO_YEARLY | public | Creem product ID for the Pro yearly plan. |
NUXT_PUBLIC_CREEM_PRODUCT_LIFETIME | public | Creem product ID for the Lifetime plan. |
See Payments for the checkout flow and webhook paths.
AI
| Variable | Scope | Required | Description |
|---|---|---|---|
NUXT_AI_GATEWAY_API_KEY | server | Feature | Vercel AI Gateway key used by server/api/chat.ts. Chat uses the Gateway, not OpenAI directly. |
NUXT_REPLICATE_API_TOKEN | server | Feature | Replicate token for image/video/audio generation. The Replicate provider is registered only when set. |
See AI Chat and Image, Video & Audio Generation.
Local vs production
- Local:
NUXT_PUBLIC_BASE_URL=http://localhost:3000. Only the database and auth secret are required to boot; add service keys as you need each feature. - Production: set
NUXT_PUBLIC_BASE_URLto your real origin, use a stableNUXT_BETTER_AUTH_SECRET, point OAuth callbacks and payment notify URLs at the production domain, and confirmNUXT_PUBLIC_AI_PUBLIC_DEMOis unset orfalseso AI routes require login. See Deployment.