Environment variables

Complete reference for all environment variables

This boilerplate uses environment variables for configuration. All sensitive credentials and environment-specific settings should be stored in .env files.

Quick start

Copy the example file: cp .env.example .env
Configure required variables (see below)
Add optional integrations as needed
Restart your dev server

Never commit .env files to version control. The .gitignore file already excludes them.

Variables reference

Variable	Required	Scope	Description
`NUXT_PUBLIC_SITE_URL`	✅	Public	Your site's public URL
`NUXT_PUBLIC_SITE_NAME`	✅	Public	Site name (emails, meta tags)
`NUXT_PUBLIC_SITE_DOMAIN`	✅	Public	Domain name (email sender)
`DATABASE_URL`	✅	Server	PostgreSQL connection string
`RESEND_API_KEY`	✅	Server	Resend API key for emails
`BETTER_AUTH_SECRET`	✅	Server	Secret for signing auth tokens
`BETTER_AUTH_URL`	✅	Server	Base URL for authentication
`SUPPORT_FORM_TARGET_EMAIL`	⚪	Server	Support form recipient
`STRIPE_SECRET_KEY`	⚪	Server	Stripe secret key
`NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`	⚪	Public	Stripe publishable key
`STRIPE_WEBHOOK_SECRET`	⚪	Server	Stripe webhook signing secret
`OPENAI_API_KEY`	⚪	Server	OpenAI API key
`ANTHROPIC_API_KEY`	⚪	Server	Anthropic API key
`GROK_API_KEY`	⚪	Server	Grok / xAI API key
`IPINFO_TOKEN`	⚪	Server	IPinfo geolocation token
`NUXT_PUBLIC_UMAMI_ID`	⚪	Public	Umami website ID
`NUXT_PUBLIC_UMAMI_HOST`	⚪	Public	Umami host URL
`NUXT_PUBLIC_VERCEL_ANALYTICS`	⚪	Public	Enable Vercel Analytics

Required variables

Site configuration

# Your site's public URL
NUXT_PUBLIC_SITE_URL="http://localhost:3000"

# Site name (used in emails, meta tags, etc.)
NUXT_PUBLIC_SITE_NAME="Your App Name"

# Domain name (used in email sender addresses)
NUXT_PUBLIC_SITE_DOMAIN="yourdomain.com"

Database

# PostgreSQL connection string
DATABASE_URL="postgresql://user:password@localhost:5432/database"

Format: postgresql://[user]:[password]@[host]:[port]/[database]

Email

# Resend API key for sending emails
RESEND_API_KEY="re_..."

See the email integration guide for setup instructions.

Authentication

# Better Auth secret key (generate with: openssl rand -base64 32)
BETTER_AUTH_SECRET="your-secret-key-here"

# Base URL for authentication
BETTER_AUTH_URL="http://localhost:3000"

See the authentication guide for setup instructions.

Never commit your actual BETTER_AUTH_SECRET to version control. Keep it secure and regenerate it if exposed.

Optional variables

Support form

# Email address to receive support form submissions
SUPPORT_FORM_TARGET_EMAIL="support@yourdomain.com"

Stripe payments

# Stripe secret key (server-side)
STRIPE_SECRET_KEY="sk_test_..."

# Stripe publishable key (client-side)
NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."

# Webhook signing secret from Stripe dashboard
STRIPE_WEBHOOK_SECRET="whsec_..."

Payment mode (auth or authless) is configured in app/config/payments.config.ts. See the payments integration guide for Stripe setup.

AI providers

# OpenAI API key for GPT models
OPENAI_API_KEY="sk-..."

# Anthropic API key for Claude models
ANTHROPIC_API_KEY="sk-ant-..."

# Grok / xAI API key
GROK_API_KEY="xai-..."

See the AI integration guide for API key setup.

Geolocation (IPinfo)

# IPinfo API token for IP geolocation
IPINFO_TOKEN="your_token"

See the geolocation guide for setup instructions.

Analytics

# Umami Analytics (both required to enable)
NUXT_PUBLIC_UMAMI_ID="your-website-id"
NUXT_PUBLIC_UMAMI_HOST="https://cloud.umami.is"

# Vercel Analytics (set to any truthy value to enable)
NUXT_PUBLIC_VERCEL_ANALYTICS="true"

See the analytics guide for setup instructions.

Variable naming conventions

Nuxt uses specific prefixes for environment variables:

`NUXT_PUBLIC_*`

Variables with this prefix are exposed to the client-side:

# ✅ Accessible in browser
NUXT_PUBLIC_SITE_URL="https://example.com"
NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."

Access in components:

<script setup>
const config = useRuntimeConfig()
console.log(config.public.siteUrl) // Works in browser
</script>

Never use NUXT_PUBLIC_ for secrets! These are exposed to the browser and visible in the source code.

Standard variables

Variables without a special prefix are server-side only:

# ✅ Only accessible on server
DATABASE_URL="postgresql://..."
STRIPE_SECRET_KEY="sk_test_..."
RESEND_API_KEY="re_..."

Access only in server code:

// ✅ Works in server/api routes
const config = useRuntimeConfig()
console.log(config.stripeSecretKey)

// ❌ Returns undefined in browser

Accessing runtime config

All environment variables are mapped to runtime config in nuxt.config.ts.

In server code:

server/api/example.ts

export default defineEventHandler(event => {
  const config = useRuntimeConfig()

  // Access server-only variables
  const dbUrl = config.databaseUrl
  const stripeKey = config.stripeSecretKey

  // Access public variables
  const siteUrl = config.public.siteUrl
})

In client code:

<script setup>
const config = useRuntimeConfig()

// ✅ Public variables work
console.log(config.public.siteUrl)

// ❌ Server variables are undefined
console.log(config.stripeSecretKey) // undefined
</script>

Environment-specific configuration

You can create different .env files for each environment:

.env - Local development
.env.staging - Staging environment
.env.production - Production environment

Use test/sandbox keys in development and staging, and live keys only in production.

Platform-specific configuration

Vercel

Add environment variables in the Vercel dashboard:

Go to your project settings
Navigate to "Environment Variables"
Add each variable with appropriate scope (Production/Preview/Development)

Netlify

Add in Netlify dashboard or netlify.toml:

netlify.toml

[context.production.environment]
  NUXT_PUBLIC_SITE_URL = "https://yourdomain.com"

Docker

Use environment variables in docker-compose.yml:

docker-compose.yml

version: '3'
services:
  app:
    build: .
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - NUXT_PUBLIC_SITE_URL=${NUXT_PUBLIC_SITE_URL}

Or use an .env file:

services:
  app:
    env_file:
      - .env.production

Security best practices

Never commit .env files - already excluded in .gitignore
Use test keys in development/staging, live keys only in production
Rotate keys after team changes or if exposed
Use restricted API keys with minimal required permissions (especially for Stripe and database)

Troubleshooting

Variables not loading

Check file name: Must be exactly .env
Restart dev server: Changes require restart
Check syntax: No spaces around =

# ❌ Wrong
VARIABLE = "value"

# ✅ Correct
VARIABLE="value"

Public variables returning undefined

Add NUXT_PUBLIC_ prefix:

# ❌ Not accessible in browser
SITE_URL="https://example.com"

# ✅ Accessible in browser
NUXT_PUBLIC_SITE_URL="https://example.com"

Runtime config not updating

Clear Nuxt cache and restart:

rm -rf .nuxt
pnpm dev

Additional resources

For production, consider using a secrets management service like AWS Secrets Manager or HashiCorp Vault.

Cursor rules

Customize AI coding assistant rules for your project

Deployment

Deploy your Nuxt application to production