If you have found dotenv-expand useful, consider checking out dotenvx for encrypting your .env files. Thank you for using dotenv. 🙏

dotenv-expand

Dotenv-expand is a zero-dependency module that adds variable expansion, command substitution, and encrypted value support on top of dotenv.

 

Usage

Install it alongside dotenv.

npm install dotenv dotenv-expand --save

Create a .env file in the root of your project:

# .env
USERNAME="dotenv"
DATABASE_URL="postgres://${USERNAME}@localhost/my_database"

As early as possible in your application, configure dotenv and expand its result:

// index.js
const dotenv = require('dotenv')
const dotenvExpand = require('dotenv-expand')

dotenvExpand.expand(dotenv.config())

console.log(process.env.DATABASE_URL)

$ node index.js
postgres://dotenv@localhost/my_database

That's it. process.env now contains the expanded values from your .env file.

 

Advanced

Preload

Consider using dotenvx instead. It includes expansion, command substitution, and encrypted .env support across languages and platforms:

dotenvx run -- node your_script.js

Use Node's --require (-r) option to load and expand .env before your application starts:

node -r dotenv-expand/config your_script.js

The preload entry is self-contained; you do not need to separately install dotenv.

Configuration options can be passed as command-line arguments:

node -r dotenv-expand/config your_script.js dotenv_config_path=/custom/path/to/.env

Or as environment variables:

DOTENV_CONFIG_ENCODING=latin1 node -r dotenv-expand/config your_script.js

Command-line arguments take precedence over environment variables.

pnpm

pnpm add dotenv dotenv-expand

Command Substitution

Use $(command) to replace an expression with the command's output:

NODE_VERSION=$(node --version)

Only use command substitution with .env files you trust. Commands run with the permissions of the current process.

Encrypted Values

Use dotenvx to encrypt your .env file. dotenv-expand automatically decrypts encrypted: values when DOTENV_PRIVATE_KEY is set:

DOTENV_PRIVATE_KEY="<private key>" node -r dotenv-expand/config your_script.js

Keep the private key separate from the encrypted .env file—for example, in your cloud platform's secrets manager. Read the dotenvx whitepaper for more details.

Custom Process Environment

Use processEnv to write expanded values to an object other than process.env:

const dotenvExpand = require('dotenv-expand')

const myEnv = {}

dotenvExpand.expand({
  processEnv: myEnv,
  parsed: {
    HELLO: 'World'
  }
})

console.log(myEnv.HELLO) // World
console.log(process.env.HELLO) // undefined

Interpolation Syntax

dotenv-expand supports braced and unbraced expansion, default values, and alternate values:

BASIC="basic"
BRACED=${BASIC}
UNBRACED=$BASIC
DEFAULT=${MISSING:-default}
ALTERNATE=${BASIC:+alternate}

See the complete interpolation rules.

 

FAQ

What rules does the expansion engine follow?

See a full list of rules here.

How does command substitution work?

Use $(command) in your .env file. dotenv-expand runs the command and replaces the expression with its output. See the Command Substitution example under Advanced.

How does encryption work?

Use dotenvx to encrypt your .env file. dotenv-expand automatically decrypts encrypted: values when DOTENV_PRIVATE_KEY is set.

DOTENV_PRIVATE_KEY="<private key>" node -r dotenv-expand/config your_script.js

Keep the private key separate from the encrypted .env file—for example, in your cloud platform's secrets manager. Read the dotenvx whitepaper for more details.

Is it safe to commit an encrypted `.env` file?

Yes, as long as the corresponding DOTENV_PRIVATE_KEY is stored separately and never committed with it. Use dotenvx to create and manage the encrypted file.

How can I avoid expanding pre-existing envs?

As of v12.0.0 dotenv-expand no longer expands process.env.

If you need this ability, use dotenvx and ship an encrypted .env file with your code, allowing safe expansion at runtime.

How can I override an existing environment variable?

Use dotenvx, as dotenv-expand does not support this.

dotenv-expand is a separate module (without knowledge of the loading of process.env and the .env file) and so cannot reliably know what to override.

 

Docs

Expand

expand expands, evaluates, and decrypts values in a dotenv result:

const dotenvExpand = require('dotenv-expand')

const result = dotenvExpand.expand({
  parsed: {
    BASIC: 'basic',
    BASIC_EXPAND: '${BASIC}',
    BASIC_EXPAND_SIMPLE: '$BASIC'
  }
})

console.log(result.parsed)

Options

processEnv

Default: process.env

Specify an object to read existing values from and write expanded values to.

parsed

The parsed key-value object to expand. This is normally the result of dotenv.config().

 

Contributing

See CONTRIBUTING.md.

CHANGELOG

See CHANGELOG.md.

Who's using dotenv-expand?

These npm modules depend on it.