# motdotla/dotenv architecture

> Architecture diagram of the GitHub repository motdotla/dotenv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/motdotla/dotenv
- Repository: https://github.com/motdotla/dotenv

## Overview

dotenv loads key/value settings from .env files into a process environment, either through its JavaScript API or by launching a command with the CLI. The core path covers file parsing, option resolution, and environment population; the CLI separately resolves run arguments and starts a child process. The README also documents preload imports and multiple-file loading. Source excerpts show the principal calls; README-described behavior is cited where implementation details were not sampled.

Main entry points: [`lib/main.js`](https://github.com/motdotla/dotenv/blob/master/lib/main.js) (dotenv API), [`cli.js`](https://github.com/motdotla/dotenv/blob/master/cli.js) (CLI Entry), [`config.js`](https://github.com/motdotla/dotenv/blob/master/config.js) (Preload Entry), [`lib/spawn-command.js`](https://github.com/motdotla/dotenv/blob/master/lib/spawn-command.js) (Command Launcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Environment API"]
  node_main["dotenv API<br/>[main.js]"]
  node_parser["Env Parser<br/>[main.js]"]
  node_populator["Env Population<br/>[main.js]"]
  node_process_env["Process Environment"]
  node_preload["Preload Entry<br/>[config.js]"]
end

subgraph group_cli["Command Runner"]
  node_cli_entry["CLI Entry<br/>[cli.js]"]
  node_run_options["Run Options<br/>[cli.js]"]
  node_command_loader["CLI Env Loader<br/>[cli.js]"]
  node_spawn["Command Launcher<br/>[spawn-command.js]"]
end

subgraph group_options["Configuration"]
  node_option_env["Env Option Resolver<br/>[config-options.js]"]
end

node_app(("Application"))
node_cli_user(("CLI User"))
node_env_file[".env Files"]
node_child(("Child Command"))

node_app -->|"calls config"| node_main
node_app -->|"imports preload"| node_preload
node_preload -->|"configures"| node_main
node_main -->|"parses contents"| node_parser
node_main -->|"populates values"| node_populator
node_parser -->|"provides parsed values"| node_populator
node_main -->|"reads files"| node_env_file
node_populator -->|"writes values"| node_process_env
node_main -->|"resolves env options"| node_option_env
node_cli_user -->|"runs command"| node_cli_entry
node_cli_entry -->|"resolves arguments"| node_run_options
node_run_options -->|"reads defaults"| node_option_env
node_cli_entry -->|"loads settings"| node_command_loader
node_command_loader -->|"reads files"| node_env_file
node_command_loader -->|"uses parse and populate"| node_main
node_command_loader -->|"injects values"| node_process_env
node_cli_entry -->|"launches command"| node_spawn
node_spawn -->|"spawns process"| node_child
node_process_env -->|"inherited by"| node_child

click node_main "https://github.com/motdotla/dotenv/blob/master/lib/main.js"
click node_parser "https://github.com/motdotla/dotenv/blob/master/lib/main.js"
click node_populator "https://github.com/motdotla/dotenv/blob/master/lib/main.js"
click node_preload "https://github.com/motdotla/dotenv/blob/master/config.js"
click node_cli_entry "https://github.com/motdotla/dotenv/blob/master/cli.js"
click node_run_options "https://github.com/motdotla/dotenv/blob/master/cli.js"
click node_command_loader "https://github.com/motdotla/dotenv/blob/master/cli.js"
click node_spawn "https://github.com/motdotla/dotenv/blob/master/lib/spawn-command.js"
click node_option_env "https://github.com/motdotla/dotenv/blob/master/lib/config-options.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_parser,node_populator,node_process_env,node_preload,node_cli_user toneBlue
class node_cli_entry,node_run_options,node_command_loader,node_spawn toneAmber
class node_option_env toneMint
class node_app,node_env_file,node_child toneIndigo
```

## Components

### Environment API

- [dotenv API](https://github.com/motdotla/dotenv/blob/master/lib/main.js): `lib/main.js`
- [Env Parser](https://github.com/motdotla/dotenv/blob/master/lib/main.js): `lib/main.js`
- [Env Population](https://github.com/motdotla/dotenv/blob/master/lib/main.js): `lib/main.js`
- **Process Environment**
- [Preload Entry](https://github.com/motdotla/dotenv/blob/master/config.js): `config.js`

### Command Runner

- [CLI Entry](https://github.com/motdotla/dotenv/blob/master/cli.js): `cli.js`
- [Run Options](https://github.com/motdotla/dotenv/blob/master/cli.js): `cli.js`
- [CLI Env Loader](https://github.com/motdotla/dotenv/blob/master/cli.js): `cli.js`
- [Command Launcher](https://github.com/motdotla/dotenv/blob/master/lib/spawn-command.js): `lib/spawn-command.js`

### Configuration

- [Env Option Resolver](https://github.com/motdotla/dotenv/blob/master/lib/config-options.js): `lib/config-options.js`

### Other components

- **Application**
- **CLI User**
- **.env Files**
- **Child Command**

## Connections

- Application → dotenv API: calls config (evidence: `README.md`)
- Application → Preload Entry: imports preload (evidence: `README.md`)
- Preload Entry → dotenv API: configures (evidence: `config.js`)
- dotenv API → Env Parser: parses contents (evidence: `lib/main.js`)
- dotenv API → Env Population: populates values (evidence: `lib/main.js`)
- Env Parser → Env Population: provides parsed values (evidence: `lib/main.js`)
- dotenv API → .env Files: reads files (evidence: `lib/main.js`)
- Env Population → Process Environment: writes values (evidence: `lib/main.js`)
- dotenv API → Env Option Resolver: resolves env options (evidence: `lib/main.js`)
- CLI User → CLI Entry: runs command (evidence: `cli.js`)
- CLI Entry → Run Options: resolves arguments (evidence: `cli.js`)
- Run Options → Env Option Resolver: reads defaults (evidence: `cli.js`)
- CLI Entry → CLI Env Loader: loads settings (evidence: `cli.js`)
- CLI Env Loader → .env Files: reads files (evidence: `cli.js`)
- CLI Env Loader → dotenv API: uses parse and populate (evidence: `cli.js`)
- CLI Env Loader → Process Environment: injects values (evidence: `cli.js`)
- CLI Entry → Command Launcher: launches command (evidence: `cli.js`)
- Command Launcher → Child Command: spawns process (evidence: `lib/spawn-command.js`)
- Process Environment → Child Command: inherited by (evidence: `README.md`)
