Environment Variables

NuxtBase uses .env.example as the configuration baseline and validates the final runtime values in server/utils/env.ts.

That validation is important: if a required value is missing, or if a provider needs a matching pair of variables, the app fails early instead of failing later in production.

Start With the Example File

1. Copy .env.example to .env

   cp .env.example .env

2. Immediately remove or blank out provider placeholders you are not using yet

   The template .env.example includes non-empty placeholder values such as:

   NUXT_STRIPE_SECRET_KEY=sk_test_...
   NUXT_OPENAI_API_KEY=sk-...

   Do not leave those fake values in place. If you are not setting up that provider yet, comment the line out or set it to an empty value:

   # NUXT_STRIPE_SECRET_KEY=
   # NUXT_OPENAI_API_KEY=
   # NUXT_OPENROUTER_API_KEY=

3. Fill in the minimum values for your first local run

   NUXT_PUBLIC_SITE_URL=http://localhost:3000
   DATABASE_URL=postgresql://postgres:postgres@localhost:5432/core-b2b
   BETTER_AUTH_SECRET=replace-with-a-random-secret
   BETTER_AUTH_URL=http://localhost:3000

4. Add optional providers only when you are ready to test that feature

Tip

Generate BETTER_AUTH_SECRET with a real random value. The template comments recommend either openssl rand -base64 32 or npx @better-auth/cli@latest secret.

Caution

Copying .env.example is only the starting point. For optional providers like Stripe and AI, a fake non-empty key does not behave like “disabled”. In the template code, any non-empty NUXT_STRIPE_SECRET_KEY attempts real Stripe initialization, and AI provider setup also follows the configured provider path.

Minimum Required for First Run

These values are the practical minimum if you want to boot the app locally:

Variable	Why it is required
NUXT_PUBLIC_SITE_URL	Used for links, callbacks, and public runtime config
DATABASE_URL	Required by Drizzle and all persisted product flows
BETTER_AUTH_SECRET	Required to sign auth data securely
BETTER_AUTH_URL	Required by Better Auth and trusted origin setup

NUXT_PUBLIC_APP_NAME is recommended, but not required for first boot. If you omit it, the template falls back to the default app name from siteConfig.appName.

Everything else can be added in stages, but only after you clear unused provider placeholders from the copied example file.

How NuxtBase Groups Configuration

Group	Main variables	Required when
App	NUXT_PUBLIC_SITE_URL, optional NUXT_PUBLIC_APP_NAME	Site URL always; app name only when you want to override the default brand label
Database	DATABASE_URL	Always
Auth base config	BETTER_AUTH_SECRET, BETTER_AUTH_URL	Always
OAuth	GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET	Only if enabling Google or GitHub login
Billing	NUXT_STRIPE_SECRET_KEY, NUXT_STRIPE_WEBHOOK_SECRET, NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY, four Stripe price IDs	Only if enabling real Stripe billing
Email	NUXT_MAIL_DRIVER, SMTP values, or Resend values	Required for real delivery beyond preview mode
AI	NUXT_AI_PROVIDER, NUXT_AI_MODEL, provider API key	Only if using AI chat
Storage	NUXT_STORAGE_PROVIDER, S3/R2 values	Only if not using local uploads
Analytics	NUXT_PUBLIC_ANALYTICS_PROVIDER and provider-specific variables	Only if enabling analytics
Ops	NUXT_REDIS_URL, INITIAL_ADMIN_EMAIL	Optional infrastructure and admin bootstrap

Validation Rules That Commonly Surprise People

NuxtBase does more than “check if a string exists”. The startup validation also enforces relationships between variables.

Paired Variables

These must be set together:

• GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET
• GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET
• NUXT_SMTP_USER and NUXT_SMTP_PASSWORD

If you set only one half of the pair, startup fails.

Storage Provider Rules

If NUXT_STORAGE_PROVIDER is s3 or r2, the template expects all of these:

S3_BUCKET=
S3_REGION=
S3_ENDPOINT=
S3_ACCESS_KEY_ID=
S3_SECRET_ACCESS_KEY=
S3_PUBLIC_URL=

For local development, the safest path is:

NUXT_STORAGE_PROVIDER=local

Analytics Defaults

If you do nothing, analytics stays disabled:

NUXT_PUBLIC_ANALYTICS_PROVIDER=none

That is the intended default for local development.

Recommended Rollout Order

Use this order unless you already know you need a specific provider on day one:

1. app URL + auth URL
2. database
3. auth secret
4. email driver
5. Stripe
6. storage
7. AI
8. analytics

This keeps the first setup small and easy to debug.

Validate Your Configuration

Once .env is in place, start the app and let the runtime validation tell you if anything is missing or malformed.

pnpm

pnpm dev

npm

npm run dev

yarn

yarn dev

If the app exits immediately, read the error message carefully. In most cases it will name the exact variable or pair that failed validation.

Caution

The repository ships with pnpm-lock.yaml and is authored around pnpm, so pnpm is still the lowest-friction default. npm and yarn equivalents are documented as well because the script names map cleanly across package managers.