ldenv

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:

ldenv <command> [...args]

This will provide to command the environment variable set in the .env, .env.local, etc... (see #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

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):

echo $GREETINGS

default values

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

ldenv echo @@GREETINGS

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

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

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

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)

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 ) and is specified by -m bonjour. this result in the env var TARGET_bonjour

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

sequential execution

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

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

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:

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

Examples:

Watch mode with a development server:

ldenv -w node server.js

Watch mode with a specific mode:

ldenv -m development -w npm run dev

Watch mode with sequential commands:

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 and 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 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.