dotenv vs Platform Inject

dotenv loads key-value pairs from a .env file into process.env on your laptop. Production platforms inject environment variables at runtime from k8s Secrets, AWS SSM, Vault, or PaaS dashboards. The Node.js code path is the same; only the source changes.

Recipe

Quick-reference recipe card - copy-paste ready.

// src/load-env.ts
import { config as dotenvConfig } from "dotenv";
 
export function bootstrapEnv() {
  if (process.env.NODE_ENV === "test") return;
  if (process.env.NODE_ENV === "production") return; // platform injects env
  dotenvConfig(); // development only
}

# Dockerfile - NO COPY .env
ENV NODE_ENV=production
# DATABASE_URL set by k8s/ECS at runtime
CMD ["node", "dist/main.js"]

When to reach for this:

• Onboarding developers who need local Postgres URLs without sharing prod credentials
• Auditing Docker images for accidental secret bake-in
• Designing CI pipelines that mirror production injection
• Migrating from .env in repo to vault-backed prod

Working Example

// src/load-env.ts
import { config as dotenvConfig } from "dotenv";
import { existsSync } from "node:fs";
 
export function bootstrapEnv(): void {
  const nodeEnv = process.env.NODE_ENV ?? "development";
 
  if (nodeEnv === "production") {
    // ECS task definition, k8s manifest, or Fly secrets set these
    return;
  }
 
  if (nodeEnv === "test") {
    // Jest/Vitest setup file sets process.env directly
    return;
  }
 
  const path = existsSync(".env.local") ? ".env.local" : ".env";
  const result = dotenvConfig({ path });
  if (result.error && !existsSync(".env.example")) {
    console.warn(`No ${path} found; copy .env.example to .env`);
  }
}
 
// src/main.ts
import { bootstrapEnv } from "./load-env";
bootstrapEnv();
import { env } from "./env"; // Zod parse after bootstrap
import express from "express";
 
const app = express();
app.listen(env.PORT);

# kubernetes deployment excerpt
env:
  - name: DATABASE_URL
    valueFrom:
      secretKeyRef:
        name: api-secrets
        key: database-url
  - name: NODE_ENV
    value: production

What this demonstrates:

• dotenv runs only in development; production trusts the orchestrator
• Docker image contains no .env file
• Same env.ts Zod schema validates both local and prod sources

Deep Dive

How It Works

• dotenv reads .env and assigns to process.env without overwriting existing keys (by default)
• Platforms set env before node starts - container entrypoint sees full process.env
• Precedence: platform env > shell export > dotenv file (when override: false)
• Secrets managers often fetch at boot and set process.env programmatically before Zod parse

Environment Matrix

Docker and Compose

# docker-compose.yml - dev only
services:
  api:
    env_file:
      - .env
    environment:
      NODE_ENV: development

• env_file in Compose is dev ergonomics, not production pattern
• Production Compose (if used) should use Docker secrets or external vault

TypeScript Notes

// Explicit guard in schema for production misconfigs
const envSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]),
  DATABASE_URL: z.string().url(),
}).refine(
  (e) => e.NODE_ENV !== "production" || !e.DATABASE_URL.includes("localhost"),
  { message: "Production DATABASE_URL cannot point to localhost" }
);

Gotchas

• Committing .env to git - Instant credential leak. Fix: .gitignore .env; commit .env.example with placeholders only.
• COPY .env in Dockerfile - Secrets in image layers forever. Fix: Runtime inject only; scan images with docker history.
• dotenv in production dependencies - Encourages prod misuse. Fix: devDependencies when only local dev loads files.
• Assuming dotenv overrides platform - override: true can clobber k8s secrets in hybrid setups. Fix: Keep default override: false; skip dotenv in prod entirely.
• Different keys per environment without schema - Staging missing STRIPE_KEY fails at payment time. Fix: One Zod schema; CI validates each environment's manifest template.

Alternatives

FAQs

Related

• Configuration Basics - twelve-factor config
• Zod & env-schema Validation - validate after inject
• Secrets Managers - vault fetch patterns
• Docker Basics - image env conventions
• Configuration Best Practices - team policy

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.