env-config

Purpose

Prevent misconfigurations from reaching production. Validate environment variables at startup, manage secrets safely, and keep config portable across local dev, CI, and production.

.env File Patterns

File Hierarchy

• .env holds shared defaults. Commit this to the repo with safe placeholder values.
• .env.local holds developer-specific overrides. Add to .gitignore.
• .env.production, .env.staging, .env.test hold environment-specific values.
• Load order (most frameworks): .env < .env.local < .env.[environment] < .env.[environment].local.

Naming Conventions

• Prefix variables with the app or service name: MYAPP_DATABASE_URL, not just DATABASE_URL.
• Use SCREAMING_SNAKE_CASE. No dots, no dashes.
• Boolean values: use true/false, not 1/0 or yes/no.
• Group related variables with a common prefix: MYAPP_REDIS_HOST, MYAPP_REDIS_PORT.

Template Files

• Maintain a .env.example with every variable, documented with comments.
• Use placeholder values that make the expected format obvious: MYAPP_API_KEY=sk_test_xxxxxxxxxxxx.
• Script a setup step that copies .env.example to .env if .env does not exist.

Validation with Zod

import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'staging', 'production']),
  PORT: z.coerce.number().int().min(1).max(65535).default(3000),
  DATABASE_URL: z.string().url(),
  API_KEY: z.string().min(10),
  ENABLE_CACHE: z.coerce.boolean().default(false),
});

export const env = envSchema.parse(process.env);

• Call this at application startup, before any other initialization.
• Fail fast with a clear error listing all missing or invalid variables.
• Export the parsed result as a typed object. Never access process.env directly elsewhere.
• Use z.coerce for numbers and booleans since env vars are always strings.

Validation with Envalid

import { cleanEnv, str, port, bool, url } from 'envalid';

export const env = cleanEnv(process.env, {
  NODE_ENV: str({ choices: ['development', 'staging', 'production'] }),
  PORT: port({ default: 3000 }),
  DATABASE_URL: url(),
  API_KEY: str(),
  ENABLE_CACHE: bool({ default: false }),
});