dotenv-expand
Extends dotenv with variable expansion support. Allows .env files to reference other variables: DATABASE_URL=postgres://${DB_USER}:${DB_PASS}@${DB_HOST}/${DB_NAME}. Works as a post-processor on top of dotenv's parsed output. Enables DRY configuration files where base variables are reused in composite values.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
BSD 2-Clause licensed. .env files with secrets should be in .gitignore. Variable expansion may expose secret values in composed variables — log with care.
⚡ Reliability
Best When
You use dotenv and want to compose environment variable values from other variables to reduce duplication in .env files.
Avoid When
You don't need variable composition — plain dotenv is simpler. For production secrets, use dedicated secrets management.
Use Cases
- • Compose environment variable values from base variables in agent .env files (connection strings, URLs)
- • Reduce duplication in agent configuration files by referencing shared variables in composite values
- • Support multiple environments where DATABASE_URL is built from shared host/user/password variables
- • Enable hierarchical configuration where base URL components are combined into full API endpoint URLs
- • Build deployment configurations where agent API URLs reference base DOMAIN and API_VERSION variables
Not For
- • Production secrets management — .env files with dotenv-expand still need to be secured; use Vault or cloud secrets for production
- • Complex templating — use mustache or handlebars for rich variable templates; dotenv-expand only handles ${VAR} substitution
- • Non-Node.js environments — dotenv-expand is Node.js only
Interface
Authentication
Local library — no authentication required. BSD 2-Clause licensed.
Pricing
BSD 2-Clause licensed. Zero cost.
Agent Metadata
Known Gotchas
- ⚠ Must call after dotenv.config(): const dotenv = require('dotenv'); const expand = require('dotenv-expand'); expand.expand(dotenv.config())
- ⚠ Circular references silently produce empty values — ${A}=${B} and ${B}=${A} will expand to empty strings without error
- ⚠ Undefined variable references expand to empty string — ${UNDEFINED_VAR} becomes '' without warning; validate required variables after expansion
- ⚠ Existing environment variables take precedence over .env file by default — dotenv-expand respects the override:false default of dotenv
- ⚠ v10+ changed API: dotenv.config() output passed to expand.expand() — check version if using older documentation
- ⚠ Windows PATH separator awareness: variable values with file paths containing backslashes may need manual handling
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for dotenv-expand.
Scores are editorial opinions as of 2026-03-06.