Env Config

Environment Variable Configuration

Set up environment variables with validation, documentation, and secure handling across environments. If target names a service (Supabase, Stripe, etc.), scope to that service's vars. Otherwise, set up the full env system.

Step 1: File Structure

Create these files in the project root:

Load order (Next.js)

Next.js loads env files in this order (later files override earlier):

1. .env (all environments)
2. .env.local (all environments, git-ignored)
3. .env.[environment] (e.g., .env.development)
4. .env.[environment].local (e.g., .env.development.local, git-ignored)

Step 2: Naming Conventions

Common variable groups

Step 3: Validate with t3-env

Install t3-env for runtime validation:

pnpm add @t3-oss/env-nextjs zod

Create src/env.ts:

import { createEnv } from '@t3-oss/env-nextjs'
import { z } from 'zod'

export const env = createEnv({
  // Server-side variables (never exposed to client)
  server: {
    DATABASE_URL: z.string().url(),
    SUPABASE_SERVICE_ROLE_KEY: z.string().min(1),
    STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
    STRIPE_WEBHOOK_SECRET: z.string().startsWith('whsec_'),
    NEXTAUTH_SECRET: z.string().min(1),
    NEXTAUTH_URL: z.string().url(),
  },

  // Client-side variables (exposed to browser)
  client: {
    NEXT_PUBLIC_APP_URL: z.string().url(),
    NEXT_PUBLIC_SUPABASE_URL: z.string().url(),
    NEXT_PUBLIC_SUPABASE_ANON_KEY: z.string().min(1),
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().startsWith('pk_'),
  },

  // Map env vars to the schema
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    SUPABASE_SERVICE_ROLE_KEY: process.env.SUPABASE_SERVICE_ROLE_KEY,
    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
    STRIPE_WEBHOOK_SECRET: process.env.STRIPE_WEBHOOK_SECRET,
    NEXTAUTH_SECRET: process.env.NEXTAUTH_SECRET,
    NEXTAUTH_URL: process.env.NEXTAUTH_URL,
    NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
    NEXT_PUBLIC_SUPABASE_URL: process.env.NEXT_PUBLIC_SUPABASE_URL,
    NEXT_PUBLIC_SUPABASE_ANON_KEY: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY,
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY:
      process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
  },

  // Skip validation in Docker builds or CI where env vars aren't needed
  skipValidation: !!process.env.SKIP_ENV_VALIDATION,
})

Usage

Import env instead of accessing process.env directly:

// Good — validated and typed
import { env } from '@/env'
const url = env.NEXT_PUBLIC_APP_URL

// Bad — unvalidated, untyped, silent failure
const url = process.env.NEXT_PUBLIC_APP_URL

This crashes at startup if required variables are missing, instead of failing silently at runtime.

Step 4: Generate .env.example

Create .env.example with every variable, no real values, and comments:

# App
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Stripe
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Auth
NEXTAUTH_SECRET=generate-with-openssl-rand-base64-32
NEXTAUTH_URL=http://localhost:3000

# Email
RESEND_API_KEY=re_...
EMAIL_FROM=onboarding@yourdomain.com

Keep .env.example in sync whenever you add or remove a variable.

Step 5: Secrets Management

Rules

Generate secrets

# Generate a random secret (e.g., for NEXTAUTH_SECRET)
openssl rand -base64 32

Production env vars

Set via your hosting platform, never in files:

# Vercel
vercel env add STRIPE_SECRET_KEY production

# Railway
railway variables set STRIPE_SECRET_KEY=sk_live_...

Step 6: Adding a New Env Var Checklist

Follow this checklist every time you add a new environment variable:

Common Patterns

Feature flags via env vars

// In env.ts
server: {
  ENABLE_NEW_BILLING: z.enum(['true', 'false']).default('false'),
}

// In code
if (env.ENABLE_NEW_BILLING === 'true') {
  // new billing logic
}

Per-environment API URLs

# .env.development
NEXT_PUBLIC_API_URL=http://localhost:3001

# .env.production
NEXT_PUBLIC_API_URL=https://api.yourdomain.com

Optional variables

// In env.ts — use .optional() for non-required vars
server: {
  SENTRY_DSN: z.string().url().optional(),
  ANALYTICS_ID: z.string().optional(),
}

Debugging Env Issues