How does dotenv work for Node.js configuration?

Direct answer

dotenv loads KEY=value pairs from a .env file into process.env at startup — use for local dev only; production injects env via Docker/CI; validate required vars with a schema and never commit secrets.

Twelve-factor apps treat config as environment — dotenv bridges local .env files to process.env so code reads process.env.DATABASE_URL uniformly across environments.

import 'dotenv/config' — loads .env from cwd early in entry file.
tsx --env-file=.env — Node 20+ native env file loading; AceDevHub import scripts use this.
.env.example — committed template without secrets; documents required keys.
Precedence — real environment variables override .env file values.

dotenv-config.mjs

import "dotenv/config";

const config = {
  port: Number(process.env.PORT ?? 4000),
  databaseUrl: process.env.DATABASE_URL,
  nodeEnv: process.env.NODE_ENV ?? "development",
};

if (!config.databaseUrl) {
  throw new Error("DATABASE_URL is required — see apps/api/.env.example");
}

export { config };