Squared Sums

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.

Environment file

Create a .env file in your project root:

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

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]

Optional variables

Email (Resend)

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

# Email address to receive support form submissions
SUPPORT_FORM_TARGET_EMAIL="support@yourdomain.com"
See the email integration guide for setup instructions.

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' (with accounts) or 'authless' (guest checkout)
NUXT_PUBLIC_PAYMENT_MODE="auth"
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

Runtime configuration

Environment variables are mapped to runtime config in nuxt.config.ts:

nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // Server-only variables
    ipinfoToken: process.env.IPINFO_TOKEN,
    supportFormTargetEmail: process.env.SUPPORT_FORM_TARGET_EMAIL,
    stripeSecretKey: process.env.STRIPE_SECRET_KEY,
    stripeWebhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
    resendApiKey: process.env.RESEND_API_KEY,
    openaiApiKey: process.env.OPENAI_API_KEY,
    anthropicApiKey: process.env.ANTHROPIC_API_KEY,
    grokApiKey: process.env.GROK_API_KEY,

    // Public variables (exposed to client)
    public: {
      siteUrl: process.env.NUXT_PUBLIC_SITE_URL,
      siteName: process.env.NUXT_PUBLIC_SITE_NAME,
      siteDomain: process.env.NUXT_PUBLIC_SITE_DOMAIN,
      stripePublishableKey: process.env.NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
      paymentMode: process.env.NUXT_PUBLIC_PAYMENT_MODE,
      umamiId: process.env.NUXT_PUBLIC_UMAMI_ID,
      umamiHost: process.env.NUXT_PUBLIC_UMAMI_HOST,
      vercelAnalytics: process.env.NUXT_PUBLIC_VERCEL_ANALYTICS,
    },
  },
})

Accessing runtime config

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

Development

Use .env for local development:

.env
NUXT_PUBLIC_SITE_URL="http://localhost:3000"
DATABASE_URL="postgresql://localhost:5432/myapp_dev"
STRIPE_SECRET_KEY="sk_test_..."

Staging

Use .env.staging or configure in your deployment platform:

.env.staging
NUXT_PUBLIC_SITE_URL="https://staging.yourdomain.com"
DATABASE_URL="postgresql://staging-db:5432/myapp_staging"
STRIPE_SECRET_KEY="sk_test_..."  # Still use test keys

Production

Use .env.production or configure in your deployment platform:

.env.production
NUXT_PUBLIC_SITE_URL="https://yourdomain.com"
DATABASE_URL="postgresql://prod-db:5432/myapp"
STRIPE_SECRET_KEY="sk_live_..."  # Use live keys 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

Validation

Add validation for required environment variables:

server/utils/config.ts
const requiredEnvVars = ['DATABASE_URL', 'NUXT_PUBLIC_SITE_URL', 'STRIPE_SECRET_KEY']

for (const envVar of requiredEnvVars) {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`)
  }
}

Or use Zod for validation:

import { z } from 'zod'

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  NUXT_PUBLIC_SITE_URL: z.string().url(),
  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
  RESEND_API_KEY: z.string().optional(),
})

envSchema.parse(process.env)

Security best practices

Never commit secrets

# .gitignore
.env
.env.*
!.env.example

Use different keys for each environment

  • Development: Test/sandbox keys
  • Staging: Test keys
  • Production: Live keys

Rotate keys regularly

Update API keys periodically, especially:

  • After team member leaves
  • If keys are exposed
  • As part of security audits

Limit key permissions

Use API keys with minimal required permissions:

  • Stripe: Use restricted API keys
  • Database: Use user with limited access

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

Reference

Use a password manager or secrets management service (like AWS Secrets Manager or HashiCorp Vault) for production credentials.

Cursor rules

Customize AI coding assistant rules for your project

Deployment

Deploy your Nuxt application to production