Environment Variables Best Practices: .env Files, Security & Secrets Management

The .env file hierarchy: what loads when

The dotenv pattern was popularized by Ruby’s Foreman gem in 2012, then ported to Node.js by motdotla in 2013 (now at 33M+ weekly npm downloads). Every major framework adopts it with a specific loading order. Understanding this order prevents the “why is my dev DB showing in production?” nightmare.

# Loading order: later files override earlier ones
# Next.js / Vite / CRA / Laravel loading hierarchy:

.env                    # Base defaults — SAFE to commit (no secrets)
.env.local              # Local machine overrides — in .gitignore
.env.development        # Development environment
.env.development.local  # Dev overrides — in .gitignore
.env.test               # Test environment
.env.production         # Production overrides — may commit (no secrets!)
.env.production.local   # Production secrets — NEVER commit

# Example: what should live where
# .env (committed):
NODE_ENV=development
APP_NAME=MyApp
LOG_LEVEL=info
PORT=3000
API_TIMEOUT_MS=30000

# .env.local (gitignored — developer's actual secrets):
DATABASE_URL=postgres://localhost:5432/myapp_dev
STRIPE_SECRET_KEY=sk_test_abc123
JWT_SECRET=local-dev-not-real-min-32-chars-abc

# .env.example (committed — documentation template):
DATABASE_URL=postgres://localhost:5432/myapp_dev
STRIPE_SECRET_KEY=sk_test_REPLACE_ME
JWT_SECRET=GENERATE_RANDOM_32_CHARS_MIN

The .env.example file is not optional — it’s the contract between your repo and every developer who clones it. A missing variable discovered at 11 PM by a new hire is a preventable outage. When building config objects from environment data, use our JSON Formatter to validate configuration structure before deploying.

Config vs secrets: the distinction that matters

Most teams make one critical mistake: they treat all environment variables as equally sensitive (or equally safe). The correct model has two tiers:

The test: if rotating the variable requires notifying external parties (Stripe, AWS, SendGrid) or revoking access from running systems, it’s a secret. Everything else is configuration. Per the OWASP Application Security Verification Standard 4.0, secrets must be stored with encryption at rest, access auditing, and revocation capability — requirements that .env files cannot satisfy.

Secret scanning: catch leaks before they become breaches

Installing a pre-commit secret scanner is the single highest-ROI security control for most development teams. It costs minutes to set up and prevents multi-day incident responses. GitHub itself runs automated secret scanning across all public repositories and notified 1+ million organizations about detected secrets in 2023 (per GitHub’s Security blog).

# Install gitleaks as a pre-commit hook
# .pre-commit-config.yaml

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.4
    hooks:
      - id: gitleaks

# Or install globally and add to .git/hooks/pre-commit:
# brew install gitleaks
# gitleaks detect --source . --verbose

# GitHub Actions: scan on every push
name: Security
on: [push, pull_request]
jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # Full history, not just latest commit
      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}

Note fetch-depth: 0 in the GitHub Actions config — without full history, the scanner only checks the latest commit, missing secrets buried in earlier commits. For analyzing security headers and HTTPS configurations on deployed applications, see our HTTPS and TLS guide.

Secrets managers compared: beyond .env files

For production systems, .env files fail on three dimensions: they have no access auditing (who read the secret?), no rotation automation, and no encryption at rest beyond filesystem permissions. Dedicated secrets managers address all three. Per the 2025 HashiCorp State of Cloud Strategy Survey, 67% of organizations now use a centralized secrets manager in production, up from 41% in 2022.

HashiCorp Vault’s dynamic secrets feature is worth calling out specifically. Instead of storing a static database password, Vault generates a short-lived credential on demand (e.g., valid for 1 hour) directly from your Postgres or MySQL server. When the lease expires, Vault automatically revokes the credential. Even if the credential leaks from an application’s memory or logs, it’s expired. This eliminates the rotation problem entirely for supported backends.

# Fetch a secret from AWS Secrets Manager at runtime
# Node.js — no .env file needed in production

import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager'

const client = new SecretsManagerClient({ region: 'us-east-1' })

async function getSecret(secretName: string): Promise<string> {
  const response = await client.send(
    new GetSecretValueCommand({ SecretId: secretName })
  )
  return response.SecretString ?? ''
}

// At startup:
const dbUrl = await getSecret('production/myapp/database-url')
const stripeKey = await getSecret('production/myapp/stripe-secret-key')

// IAM policy grants ONLY this Lambda/ECS task read access
// to these specific secrets — least privilege enforced.

Type-safe validation: fail fast, fail loudly

Environment variables arrive as strings. A missing PORT silently becomes NaN. An empty DATABASE_URL crashes on the first query, not at startup. Startup-time validation with Zod (13M+ weekly npm downloads) turns runtime mysteries into clear boot errors.

// config.ts — validate env vars at process startup
import { z } from 'zod'

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'staging', 'production']),
  PORT: z.coerce.number().int().min(1).max(65535).default(3000),
  DATABASE_URL: z.string().url().startsWith('postgres'),
  REDIS_URL: z.string().url().optional(),

  // Secrets — validate format, not value
  STRIPE_SECRET_KEY: z.string()
    .refine(k => k.startsWith('sk_live_') || k.startsWith('sk_test_'), {
      message: 'Must be a Stripe secret key (sk_live_ or sk_test_)',
    }),
  JWT_SECRET: z.string().min(32, 'JWT secret must be at least 32 characters'),

  // Multi-value — parse from comma-separated string
  CORS_ORIGINS: z.string()
    .transform(s => s.split(',').map(o => o.trim()))
    .pipe(z.string().url().array().min(1)),

  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
})

// Throws ZodError immediately if any var is missing/invalid
// TypeScript infers exact types: config.PORT is number, not string
export const config = envSchema.parse(process.env)

// For Next.js App Router, use @t3-oss/env-nextjs for
// build-time type safety on NEXT_PUBLIC_ variables.

For Python, pydantic-settings provides the same pattern: define a BaseSettings class with field types, and Pydantic validates and coerces os.environ at import time. The runtime fail-fast approach is consistent across languages.

OIDC federation: the future of keyless deployments

The highest-risk environment variable pattern is long-lived cloud credentials (AWS_ACCESS_KEY_ID, GOOGLE_APPLICATION_CREDENTIALS) stored in CI/CD secrets. These keys don’t expire, and a leaked CI/CD secret provides persistent cloud access. OpenID Connect (OIDC) federation eliminates the need to store any cloud credentials at all.

# GitHub Actions — OIDC authentication to AWS (no stored credentials)
# .github/workflows/deploy.yml

permissions:
  id-token: write   # Required for OIDC
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials via OIDC
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789:role/github-actions-deploy
          aws-region: us-east-1
          # No AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY needed!
          # GitHub requests a JWT from its OIDC provider,
          # AWS verifies it and issues a 1-hour STS token.

      - name: Deploy to ECS
        run: aws ecs update-service --cluster prod --service api --force-new-deployment

# The IAM trust policy on github-actions-deploy role:
# {
#   "Effect": "Allow",
#   "Principal": { "Federated": "arn:aws:iam::123456789:oidc-provider/token.actions.githubusercontent.com" },
#   "Condition": { "StringLike": { "token.actions.githubusercontent.com:sub": "repo:myorg/myrepo:ref:refs/heads/main" } }
# }

GitHub, GitLab, CircleCI, and Bitbucket Pipelines all support OIDC federation with AWS, GCP, and Azure. For CI/CD security practices, see our guide to CI/CD pipeline security.

Naming conventions and organization

Consistent naming prevents collisions between services and makes variables self-documenting. The universal convention is SCREAMING_SNAKE_CASE, established by POSIX and followed by every major runtime.

# DO: Service-prefixed names prevent collisions
STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

SENDGRID_API_KEY=SG.xxx
[email protected]

AWS_REGION=us-east-1
AWS_S3_BUCKET=myapp-uploads
# (Don't store AWS_ACCESS_KEY_ID in files — use OIDC or instance roles)

# DO: Explicit boolean values (pick a convention, stick to it)
FEATURE_NEW_CHECKOUT=true     # string "true"/"false"
ENABLE_RATE_LIMITING=1        # "1"/"0"

# DON'T: Ambiguous names
KEY=sk_live_...               # What service?
SECRET=abc123                 # What kind?
DB=postgres://localhost/app   # Use DATABASE_URL (conventional name)

# DON'T: Spaces around = sign (breaks dotenv parsers)
DATABASE_URL = postgres://localhost/db  # WRONG
DATABASE_URL=postgres://localhost/db    # CORRECT

# Security: use a password generator for secrets
# Target: 256+ bits of entropy minimum for signing keys
# 32 random bytes = openssl rand -hex 32

Generate cryptographically strong secrets for JWT signing and encryption keys with our Password Generator, which uses the browser’s crypto.getRandomValues() API — no server-side processing, no logging.

Framework browser-exposure prefixes

Every framework that supports SSR or static generation needs a way to distinguish server-only variables from ones safe for the browser bundle. Exposing the wrong variable to the browser is a very common source of credential leaks — the secret ends up in every user’s browser JavaScript.

SvelteKit’s approach is the most secure by default: $env/static/private throws a compile-time error if you try to import it from a client-side module, making accidental exposure impossible at build time. Next.js 14+ App Router with Server Components offers similar guarantees for variables accessed only in server components.

Production security checklist

Frequently asked questions

Related articles