dotenv

Loads environment variables from a .env file into process.env for Node.js apps.

Library
npm
v18.0.9
20,561 stars
BSD-2-Clause

Repository Health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum. How we score it →
77 /100 Good
Development Activity 92
Maintenance 52
Community 64
Maturity 60
Momentum 40

Technical Analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation. How we score it →
83 /100 Excellent
Architecture 78
Code Quality 88
Innovation 72
Learning Curve 95

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.

Used by 222 apps in this directory

TypeScript
59%
MIT

web-check

Developer Tools · Security

35,393

All-in-one OSINT dashboard that dissects any website's IP, SSL, DNS, headers, cookies, ports, trackers, and more in a single scan.

View details
81
Repo Health
75
Technical
71
Dependency
Built with
TypeScript 59%
JavaScript 22%
Astro 16%
Updated 2 weeks ago
TypeScript
88%
Other

Webiny JS

Blogging · CMS · Ecommerce

8,049

Open-source, self-hosted CMS on AWS serverless — a TypeScript framework you extend with code, not a product you configure through a UI.

View details
90
Repo Health
86
Technical
61
Dependency
Built with
TypeScript 88%
JavaScript 11%
Updated 1 weeks ago
TypeScript
96%
GPL 3.0

Wire

Collaboration · Team Chat · Video Conferencing

1,191

Open source end-to-end encrypted messaging for teams and enterprises — self-host for complete control over your communications and data.

View details
93
Repo Health
8
Technical
68
Dependency
Built with
TypeScript 96%
Updated 1 weeks ago
TypeScript
72%
AGPL 3.0

Worklenz

Collaboration · Product Management · Project Management

3,296

All-in-one open source project management for teams who want full control — plan projects, track tasks, manage resources, and monitor finances without the SaaS lock-in.

View details
87
Repo Health
7
Technical
64
Dependency
Built with
TypeScript 72%
JavaScript 21%
Updated 1 weeks ago
TypeScript
50%
Other

World Monitor

Analytics · Monitoring

90,281

Real-time global intelligence dashboard that fuses AI-synthesized news, geopolitical risk scoring, and infrastructure tracking into one open-source situational awareness platform.

View details
87
Repo Health
89
Technical
68
Dependency
Built with
TypeScript 50%
JavaScript 48%
Updated 1 weeks ago
Go
74%
AGPL 3.0

ZITADEL

Authentication

15,536

Open-source, API-first identity platform delivering multi-tenancy, Passkeys, OIDC, SAML, and SCIM without vendor lock-in.

View details
91
Repo Health
81
Technical
65
Dependency
Built with
Go 74%
TypeScript 12%
Updated 2 weeks ago

Join founders buildingwith open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on Substack
Join 750+ subscribers