This is a demo site.Purchase now

LogoTaskFlow
Create account

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

  1. Copy the example file: cp .env.example .env
  2. Configure required variables (see below)
  3. Add optional integrations as needed
  4. Restart your dev server
Never commit .env files to version control. The .gitignore file already excludes them.

Variables reference

VariableRequiredScopeDescription
NUXT_PUBLIC_SITE_URL✅PublicYour site's public URL
NUXT_PUBLIC_SITE_NAME✅PublicSite name (emails, meta tags)
NUXT_PUBLIC_SITE_DOMAIN✅PublicDomain name (email sender)
DATABASE_URL✅ServerPostgreSQL connection string
RESEND_API_KEY✅ServerResend API key for emails
BETTER_AUTH_SECRET✅ServerSecret for signing auth tokens
BETTER_AUTH_URL✅ServerBase URL for authentication
SUPPORT_FORM_TARGET_EMAIL⚪ServerSupport form recipient
STRIPE_SECRET_KEY⚪ServerStripe secret key
NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY⚪PublicStripe publishable key
STRIPE_WEBHOOK_SECRET⚪ServerStripe webhook signing secret
OPENAI_API_KEY⚪ServerOpenAI API key
ANTHROPIC_API_KEY⚪ServerAnthropic API key
GROK_API_KEY⚪ServerGrok / xAI API key
IPINFO_TOKEN⚪ServerIPinfo geolocation token
NUXT_PUBLIC_UMAMI_ID⚪PublicUmami website ID
NUXT_PUBLIC_UMAMI_HOST⚪PublicUmami host URL
NUXT_PUBLIC_VERCEL_ANALYTICS⚪PublicEnable 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:

  1. Go to your project settings
  2. Navigate to "Environment Variables"
  3. 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

  1. Check file name: Must be exactly .env
  2. Restart dev server: Changes require restart
  3. 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