dotenv

dotenv is a zero-dependency Node.js module that loads environment variables from a .env file into process.env, following the twelve-factor app methodology of keeping configuration separate from code. It has been the de facto standard for local environment configuration in the Node.js ecosystem since 2013, used by hundreds of thousands of projects to keep API keys, database URLs, and other secrets out of source control while still making them easy to access at runtime.

The library exposes a tiny, stable API: require('dotenv').config() (or import 'dotenv/config' for ESM) parses a .env file and populates process.env, plus a standalone parse() function for programmatic use and a dotenv run -- CLI for injecting variables into any child process without modifying application code.

What You Get

• A config() function that reads .env and populates process.env in one call
• A standalone parse() function for turning a string or Buffer of env-style text into a plain object without touching process.env
• A populate() function for merging parsed values into any target object, with optional override behavior
• A dotenv run -- <command> CLI for injecting .env variables into a child process without any code changes
• Support for multiline values (e.g. PEM private keys), inline comments, quoted strings, and multiple .env files via -f/options.path

Common Use Cases

• Loading local development secrets (API keys, database URLs) without committing them to version control
• Configuring 12-factor apps where the same codebase runs against different environments via different .env files
• Injecting environment variables into a script or test run with dotenv run -- node script.js without editing the script
• Parsing arbitrary env-formatted text (e.g. from a secrets manager) into a plain object with dotenv.parse()

Under The Hood

Architecture dotenv’s execution path is deliberately linear: config() resolves a .env path (or array of paths), reads each file synchronously with fs.readFileSync, and hands the raw text to parse(), a single regex-driven state machine (lib/main.js) that walks each line, strips surrounding quotes, and expands escaped newlines only inside double-quoted values. The parsed key/value map is then merged onto process.env (or a caller-supplied processEnv) by populate(), which enforces the override-vs-preserve policy and returns only the keys it actually wrote. cli.js reuses parse()/populate() directly rather than duplicating logic, so the CLI and the library share one code path end to end.

Tech Stack The package is pure CommonJS JavaScript with a companion .d.ts for TypeScript consumers (lib/main.d.ts) and has zero runtime dependencies — fs, path, and os from Node core are the only imports. package.json declares engines.node >= 12 and ships dual entry points (require('dotenv') and dotenv/config for side-effect-style imports), with standard for linting and tap for the test runner in devDependencies.

Code Quality The tests/ directory contains six focused suites (test-parse.js, test-populate.js, test-config.js, test-config-import.js, test-parse-multiline.js, test-cli.js, ~950 lines total) covering the parser’s quoting/comment/multiline edge cases, override semantics in populate(), and CLI argument parsing including error paths like a missing -f value. Error handling is explicit and typed via err.code = 'OBJECT_REQUIRED' rather than throwing bare Errors, and the configDotenv() function accumulates lastError across multiple file paths instead of failing fast, favoring partial success over hard failure.

API Design The public surface is intentionally minimal — four functions (config, configDotenv, parse, populate) cover every use case, and the single most common call, require('dotenv').config(), requires no arguments and no boilerplate. Optional behavior (custom path, encoding, override, debug/quiet output) is exposed through a single options object rather than a proliferation of methods, and the same options can be set via DOTENV_CONFIG_* environment variables for zero-code CLI configuration, which keeps the day-to-day API surface small while still supporting advanced setups.