node-env-run

library4.0.2jsnpmunverified

node-env-run is a command-line utility designed to simplify the process of loading environment variables from `.env` files and executing Node.js scripts or other commands with those variables pre-loaded. It leverages the popular `dotenv` library under the hood for parsing `.env` files. The package is currently at version 4.0.2 and appears to be actively maintained; while an explicit release cadence isn't stated in the provided documentation, updates often follow the underlying `dotenv` library or address bug fixes. Its key differentiators include flexible command execution (e.g., with `nodemon`, `python`), the ability to specify custom `.env` file paths, and options to override existing environment variables, making it a robust tool for local development setups.

devops

npm install node-env-run

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-ENV-RUN

node-env-run

devopsjavascriptv4.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

nodenv (CLI Executable)

✓ nodenv ./my-script.js

✗ import { nodenv } from 'node-env-run'

`node-env-run` is primarily a CLI tool. Its functionality is accessed via the `nodenv` executable in your shell or `package.json` scripts, not through programmatic `import` statements in JavaScript/TypeScript code.

node-env-run (npx usage)

✓ npx node-env-run ./my-script.js

✗ npx nodenv ./my-script.js

For one-off executions without global or project-local installation, `npx` provides a convenient way to run the `node-env-run` package directly. `npx` expects the package name, not the internal executable name.

TypeScript Types

✓ import type { EnvRunOptions } from 'node-env-run';

✗ import { EnvRunOptions } from 'node-env-run';

While the package ships TypeScript types, it's not designed for direct programmatic import of its core logic. Type imports are primarily for defining configurations if one were to build a wrapper around it.

This example demonstrates how to set up `node-env-run` in `package.json` to load environment variables from a `.env` file and execute the main script, showing variables being accessed.

// package.json { "name": "my-app", "version": "1.0.0", "scripts": { "start": "nodenv ." } } // .env HELLO_MESSAGE="Hello from .env!" PORT=3000 // index.js (main script) console.log(`Loading application on port ${process.env.PORT ?? 'unknown'}.`); console.log(process.env.HELLO_MESSAGE ?? 'No message loaded.'); // To run: // 1. npm install node-env-run --save-dev // 2. npm run start

node-env-run --version

Debug

Known issues

gotchaOverriding existing environment variables can lead to unexpected behavior if not handled carefully. By default, `node-env-run` will *not* override existing process environment variables.

fix

To explicitly override existing variables, use the `--force` or `-f` flag: `nodenv --force .` This should be used cautiously, especially in shared environments.

affects: >=1.0.0

gotchaCommitting `.env` files directly into version control systems (like Git) is a common security mistake, potentially exposing sensitive information (API keys, database credentials) to unauthorized parties.

fix

Always add `.env` files to your `.gitignore` to prevent them from being committed. For team collaboration, use template files (e.g., `.env.example`) to document required variables.

affects: >=1.0.0

gotchaIncorrectly specifying the path to the `.env` file will result in environment variables not being loaded, leading to runtime errors where applications expect certain configurations.

fix

Ensure the `--env` or `-E` flag points to the correct `.env` file path relative to where `nodenv` is executed. If no flag is provided, `nodenv` defaults to `./.env` in the current working directory.

affects: >=1.0.0

breakingOlder versions of `node-env-run` might have different default behaviors or argument parsing compared to the current v4.x. While the provided README doesn't explicitly detail breaking changes for v4, significant version bumps often introduce them, especially due to its dependency on `dotenv` which also has major versions.

fix

Refer to the official `dotenv` and `node-env-run` GitHub repositories for specific changelog details when upgrading from older major versions. Test your scripts thoroughly after upgrading.

affects: <4.0.0

Errors

Common errors & fixes

nodenv: command not found

The `nodenv` executable is not available in the system's PATH, either because `node-env-run` was not installed globally, or `npm run` isn't used for a local installation.

fix

If installed locally (`--save-dev`), run it via `npm run <script-name>` (e.g., `npm run dev` if `dev: "nodenv ."` is in `package.json`). If desired globally, install with `npm install -g node-env-run`. Alternatively, use `npx node-env-run`.

TypeError: Cannot read properties of undefined (reading 'SOME_ENV_VAR')` or similar errors indicating missing environment variables at runtime.

The `.env` file either wasn't found, was misconfigured, or the environment variable was not correctly defined within it.

fix

Verify the `.env` file exists at the expected path (defaults to `./.env` or the path specified by `-E`). Ensure variables are defined in `KEY=VALUE` format. Check for typos in both the `.env` file and the code accessing `process.env.KEY`.

(node:...) Warning: Accessing non-existent property 'NODE_ENV' of module exports inside the CJS wrapper of an ESM module will break in a future version.

This warning can occur when using `node-env-run` in projects mixing CommonJS and ES Modules, where Node.js's interop layer generates a warning due to a dependency's module resolution. It's usually not a direct `node-env-run` issue.

fix

While often harmless, review your project's module setup, particularly `package.json`'s `type` field and how dependencies are loaded. This warning is often transient and not directly caused by `node-env-run` itself.

Upgrade

Version history

4.0.2latest on npm

Audit

Dependencies

dotenvrequiredCore dependency for parsing `.env` files.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/dkundel/node-env-run ↗

packagehttps://www.npmjs.com/package/node-env-run ↗