motdotla/dotenv-expand

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.

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.

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.

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

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.

See a full list of rules here.

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.

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.

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.

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.

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.