https://github.com/dotenvx/dotenv-expand
Expand variables already on your machine for use in your .env file.
https://github.com/dotenvx/dotenv-expand
config dotenv env environment expand secrets
Last synced: about 10 hours ago
JSON representation
Expand variables already on your machine for use in your .env file.
- Host: GitHub
- URL: https://github.com/dotenvx/dotenv-expand
- Owner: dotenvx
- License: bsd-3-clause
- Created: 2016-01-20T04:30:26.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2026-07-29T18:34:11.000Z (7 days ago)
- Last Synced: 2026-08-03T10:04:30.791Z (2 days ago)
- Topics: config, dotenv, env, environment, expand, secrets
- Language: JavaScript
- Homepage: https://dotenvx.com/open-source
- Size: 962 KB
- Stars: 1,056
- Watchers: 3
- Forks: 99
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
> If you have found dotenv-expand useful, consider checking out [dotenvx](https://github.com/dotenvx/dotenvx) for encrypting your `.env` files. Thank you for using dotenv. 🙏
# dotenv-expand [](https://www.npmjs.com/package/dotenv-expand) [](https://www.npmjs.com/package/dotenv-expand)
Dotenv-expand is a zero-dependency module that adds variable expansion, command substitution, and encrypted value support on top of [dotenv](https://github.com/motdotla/dotenv).
## Usage
Install it alongside dotenv.
```sh
npm install dotenv dotenv-expand --save
```
Create a `.env` file in the root of your project:
```ini
# .env
USERNAME="dotenv"
DATABASE_URL="postgres://${USERNAME}@localhost/my_database"
```
As early as possible in your application, configure dotenv and expand its result:
```javascript
// index.js
const dotenv = require('dotenv')
const dotenvExpand = require('dotenv-expand')
dotenvExpand.expand(dotenv.config())
console.log(process.env.DATABASE_URL)
```
```sh
$ 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](https://github.com/dotenvx/dotenvx) instead. It includes expansion, command substitution, and encrypted `.env` support across languages and platforms:
>
> ```sh
> dotenvx run -- node your_script.js
> ```
Use Node's `--require` (`-r`) option to load and expand `.env` before your application starts:
```sh
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:
```sh
node -r dotenv-expand/config your_script.js dotenv_config_path=/custom/path/to/.env
```
Or as environment variables:
```sh
DOTENV_CONFIG_ENCODING=latin1 node -r dotenv-expand/config your_script.js
```
Command-line arguments take precedence over environment variables.
pnpm
```sh
pnpm add dotenv dotenv-expand
```
Command Substitution
Use `$(command)` to replace an expression with the command's output:
```ini
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](https://dotenvx.com) to encrypt your `.env` file. dotenv-expand automatically decrypts `encrypted:` values when `DOTENV_PRIVATE_KEY` is set:
```sh
DOTENV_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](https://dotenvx.com/dotenvx.pdf?v=README) for more details.
Custom Process Environment
Use `processEnv` to write expanded values to an object other than `process.env`:
```javascript
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:
```ini
BASIC="basic"
BRACED=${BASIC}
UNBRACED=$BASIC
DEFAULT=${MISSING:-default}
ALTERNATE=${BASIC:+alternate}
```
See the complete [interpolation rules](https://dotenvx.com/docs/env-file#interpolation).
## FAQ
What rules does the expansion engine follow?
See a full list of rules [here](https://dotenvx.com/docs/env-file#interpolation).
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](https://dotenvx.com) to encrypt your `.env` file. dotenv-expand automatically decrypts `encrypted:` values when `DOTENV_PRIVATE_KEY` is set.
```sh
DOTENV_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](https://dotenvx.com/dotenvx.pdf?v=README) 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](https://dotenvx.com) 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](https://dotenvx.com) and ship an encrypted `.env` file with your code, allowing safe expansion at runtime.
How can I override an existing environment variable?
Use [dotenvx](https://dotenvx.com), 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:
```javascript
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](CONTRIBUTING.md).
## CHANGELOG
See [CHANGELOG.md](CHANGELOG.md).
## Who's using dotenv-expand?
[These npm modules depend on it.](https://www.npmjs.com/browse/depended/dotenv-expand)