# ldenv

> load multiple env files based on mode

Latest version **0.6.0** (published 2026-07-30) · 0 weekly downloads

## Install

```sh
npm install ldenv
pnpm add ldenv
yarn add ldenv
bun add ldenv
```

Provides the command `ldenv`.

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.6.0 |
| Published | 2026-07-30 |
| First published | 2023-04-24 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 5 |
| Unpacked size | 311.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | wighawag |

## Links

- npm: https://www.npmjs.com/package/ldenv
- npm.io page: https://npm.io/package/ldenv

## Dependencies (5)

- [dotenv](https://npm.io/package/dotenv.md) ^16.0.3
- [lodash-es](https://npm.io/package/lodash-es.md) ^4.17.23
- [cross-spawn](https://npm.io/package/cross-spawn.md) ^7.0.6
- [dotenv-expand](https://npm.io/package/dotenv-expand.md) ^10.0.0
- [@parcel/watcher](https://npm.io/package/@parcel/watcher.md) ^2.5.6

## Recent versions

- 0.6.0 (latest) — 2026-07-30
- 0.5.0 — 2026-03-30
- 0.4.0 — 2026-03-29
- 0.3.16 — 2025-11-22
- 0.3.15 — 2025-11-06
- 0.3.14 — 2025-09-16
- 0.3.13 — 2025-09-16
- 0.3.12 — 2024-12-12
- 0.3.11 — 2024-11-05
- 0.3.10 — 2024-04-06
- 0.3.9 — 2023-11-30
- 0.3.8 — 2023-11-29
- 0.3.7 — 2023-06-10
- 0.3.6 — 2023-06-10
- 0.3.5 — 2023-05-10
- … 12 more at https://npm.io/package/ldenv/versions

## README

This module is both a module to be imported and a command line utility that load environment variables from dot env files

# Use as a command-line

ldenv is a simple yet very powerful command line tool

Its basic purpose is to load .env file and execute a command with the environment set for it

## Basic usage:

```bash
ldenv <command> [...args]
```

This will provide to `command` the environment variable set in the `.env`, `.env.local`, etc... (see [#import-as-module](#import-as-module) for details.

## ldenv can resolve variable in the command line itself:

ldenv also support resolving variable in the command and args provided.

the following will display the content of the environment variable "GREETINGS" if it is defined in one of the `.env` files

```bash
ldenv echo @@GREETINGS
```

contract this with using the shell (where GREETINGS will not be resolved unless the dotenv file was injected in the environment to begin with):

```bash
echo $GREETINGS
```

## default values

By default, if a env variable requested is missing, ldenv will abort with an error

```bash
ldenv echo @@GREETINGS
```

You can instead provide a default value, including the empty string (which is equivalent to not setting the variable):

```bash
ldenv echo @@GREETINGS@:<default value>@:
```

You can also use the commas seperated list of env variable to fallback on

```bash
ldenv echo @@NON_EXISTENT,GREETINGS
```

note that you can still provide prefix and suffix (note the need for `@:` to let ldenv know where the env name stop)

```bash
ldenv echo _@@NON_EXISTENT,GREETINGS@:_
```

## env variable name based on another env variable

ldenv allow you to resolve env variable whose name depends on another env variable too.

Here we construct the env var name `TARGET_<mode>` where mode is the mode used by ldenv (see [#import-as-module](#import-as-module) ) and is specified by `-m bonjour`. this result in the env var `TARGET_bonjour`

```bash
ldenv -m bonjour echo @@GREETINGS @@TARGET_:MODE
```

## sequential execution

ldenv also support executing multiple commands by wrapping further command using `~~`

```bash
ldenv echo @@NON_EXISTENT,GREETINGS ~~ echo next ~~
```

```bash
ldenv echo @@NON_EXISTENT,GREETINGS ~~ echo next ~~ echo again ~~
```

## Watch Mode

ldenv supports a watch mode that monitors `.env` files for changes and automatically re-runs your command when changes are detected.

### Basic watch usage:

```bash
ldenv -w <command> [...args]
```

### Examples:

Watch mode with a development server:

```bash
ldenv -w node server.js
```

Watch mode with a specific mode:

```bash
ldenv -m development -w npm run dev
```

Watch mode with sequential commands:

```bash
ldenv -w npm run build ~~ npm run serve ~~
```

### Behavior:

- When any `.env` file changes, the running process receives SIGTERM for graceful shutdown
- Environment variables are reloaded fresh from the `.env` files
- External environment variables (set before ldenv runs) are preserved
- The command is then re-executed with the new environment

### Notes:

- Watch mode monitors all loaded `.env` files (`.env`, `.env.local`, `.env.<mode>`, etc.)
- Changes are debounced to prevent rapid restarts
- Press Ctrl+C to stop watch mode

# Import As Module

This module expose a single function that uses [dotenv](https://github.com/motdotla/dotenv) and [dotenv-expand](https://github.com/motdotla/dotenv-expand) to load additional environment variables from the following files in your environment directory:

```
.env                # loaded in all cases
.env.local          # loaded in all cases, ignored by git
.env.[mode]         # only loaded in specified mode
.env.[mode].local   # only loaded in specified mode, ignored by git
```

> ### Mode
>
> The mode is resolved (in order) from: the `mode` option / `-m` flag / `@@` arg, then the
> env var named by `MODE_ENV` (defaults to `MODE`), then the `defaultMode` option / `-d` flag
> (or the current git branch when `--git` is used).
>
> When **no mode is configured**, only `.env` and `.env.local` are loaded and the mode env
> var (e.g. `MODE`) is **left unset** — it is no longer defaulted to `'local'`. This avoids
> polluting the environment (note that `'local'` is reserved by some tools, e.g. Vite) while
> keeping the same file-loading behavior.
>
> When a mode is set, `.env.<mode>` and `.env.<mode>.local` are loaded in addition, and the
> resolved mode is exposed via the mode env var so commands can reference it (e.g. `@@MODE`).

> Env Loading Priorities
>
> An env file for a specific mode (e.g. `.env.production`) will take higher priority than a generic one (e.g. `.env`).
>
> In addition, environment variables that already exist when the function is executed have the highest priority and will not be overwritten by `.env` files.
>
> `.env` files are loaded at soon as the function is invoked.

Also, because the module also uses [dotenv-expand](https://github.com/motdotla/dotenv-expand) it expand variables out of the box. To learn more about the syntax, check out their docs.

Note that if you want to use $ inside your environment value, you have to escape it with `\.`

```
KEY=123
NEW_KEY1=test$foo   # test
NEW_KEY2=test\$foo  # test$foo
NEW_KEY3=test$KEY   # test123
```

> SECURITY NOTES
>
> `.env.*.local` files are local-only and can contain sensitive variables. You should add `*.local` to your `.gitignore` to avoid them being checked into git.

---
_Source: https://npm.io/package/ldenv · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._