The Real Role of .env
A .env file is how "config comes from the environment" gets practiced: the code never reads files, only process.env, and something external injects it. .env is a local development convenience that loads a file into the environment at startup. It must never be committed — once committed, the secret lives permanently in Git history and deleting the file does not remove it.
The community pattern is committing .env.example with keys but no values, which new developers copy to .env. That works, with two conditions: .gitignore must cover .env plus every .env.* variant (.env.local, .env.production), and CI must never generate real config by copying the example — that would hardcode secrets into the pipeline definition.
A safer model merges local sources by priority: system environment variables > project .env.local > project .env > global ~/.env. Then a temporary override on one machine never pollutes the repo default.
# .gitignore —— must cover every variant
.env
.env.*
!.env.example
# .env.example —— key names only, no values
DATABASE_URL=
REDIS_URL=
SESSION_SECRET=
STRIPE_SECRET_KEY=
FEATURE_NEW_CHECKOUT=false
# Local startup: dotenv only reads the file into the environment
import "dotenv/config"
const sessionSecret = process.env.SESSION_SECRET
if (!sessionSecret) {
throw new Error("SESSION_SECRET is required")
}
console.log(sessionSecret.length >= 32 ? "secret ok" : "secret too short")Four Stages: Choose by Team Size
Stage one, plain .env: 1-5 people, no compliance requirement, few secret types (a database password, one third-party key). The critical work here is making startup config validation a hard failure — exit at boot naming the missing key, instead of failing later on the first database call.
Stage two, platform environment variables: managed platforms (Cloud Run, Heroku, Vercel) provide a config UI, suitable for static values (API endpoints, public client IDs). Its weaknesses are no versioning, no approval flow, no audit trail — and every config edit is an implicit release.
Stage three, container injection: Kubernetes puts non-sensitive values in ConfigMaps and secrets in Secrets, injected into pods as env vars or mounted files. Config now travels with the deployment spec and can be reviewed in a dry-run; the cost is that base64 is not encryption, so you still need etcd encryption at rest or an external secret system.
Stage four, a secret manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault): versioning, automated rotation, fine-grained IAM and full audit trails. It fits scenarios with many secrets, frequent rotation needs and compliance demands. The tradeoffs are added network latency, an availability dependency and new friction for local development — which is why it usually arrives last.
# Level 1: hard validation at startup + explicit error
const required = ["DATABASE_URL", "SESSION_SECRET", "STRIPE_SECRET_KEY"] as const
const missing = required.filter((k) => !process.env[k])
if (missing.length > 0) {
console.error("Missing required config:", missing.join(", "))
process.exit(1)
}
# Level 3: inject via K8s, config and deployment description share one source
example@prod:
containers:
- name: app
env:
- name: DATABASE_URL
valueFrom:
secretKeyRef:
name: app-secrets
key: database-url
- name: LOG_LEVEL
value: "info"
envFrom:
- configMapRef:
name: app-configSecret Rotation: Overlap Windows Are the Basic Skill
The hard part of rotation is never generating a new value; it is making old and new simultaneously valid during an overlap window. Any rotation scheme must answer: when does the old key die, who triggers it, and how do you roll back. Rotation without an overlap window is a planned brief outage for the whole site.
The standard approach is dual-key support: two environment variables, first ship a version accepting both, then switch to the new key, observe, then revoke the old one. This matters most for symmetric session secrets, where you must decrypt historical tokens with either key, or embed a key id in the ciphertext so each version resolves to its key.
Do not forget hard-to-switch cases such as database passwords. The safe pattern is "create a second user or second password, shift traffic gradually, revoke the old user" rather than changing the password in place. Write the rotation action into a runbook with trigger conditions, owner, verification commands and rollback steps.
# Dual-key overlap: tolerate first, switch next, revoke last
const legacyKey = process.env.SESSION_SECRET_LEGACY
const currentKey = process.env.SESSION_SECRET_CURRENT
function sign(payload: string): string {
return hmac(payload, currentKey!) // Sign with the new key only
}
function verify(token: string): boolean {
const payload = decode(token)
if (hmacVerify(payload, currentKey!)) return true
return legacyKey ? hmacVerify(payload, legacyKey) : false // Still accept the old key during the transition
}
# Revoke after the observation window: delete SESSION_SECRET_LEGACY and the branch in code becomes deadCommon Failure Modes and How to Avoid Them
The first failure mode is committing .env.production. Block it at two layers with pre-commit and server-side pre-receive hooks, and add a CI step that scans full history with a tool such as gitleaks rather than only the HEAD commit.
The second is mixing config and secrets in one ConfigMap. If logs dump the whole environment, secrets leak. Enforce an allowlist at the code level (log only LOG_LEVEL, APP_VERSION) and apply the same redaction to CI logs.
The third is local development friction. Secret managers usually require login or VPN; the fix is to cache a short-lived credential locally (~/.aws/credentials, or gcloud auth application-default login) instead of copying production secrets into .env. The fourth is config drift when environments carry different key sets — cross-validate them against one schema (JSON Schema or zod).
// Only whitelisted config may enter the logs
const LOGGABLE_KEYS = ["LOG_LEVEL", "APP_VERSION", "NODE_ENV", "REGION"] as const
function safeEnvSnapshot(): Record<string, string> {
return Object.fromEntries(LOGGABLE_KEYS.filter((k) => process.env[k]).map((k) => [k, process.env[k]!]))
}
console.log("startup", safeEnvSnapshot())
# Scan for historical leaks in CI
gitleaks detect --source . --redact --exit-code 1