Node Environment Run

4.0.2 · active · verified Tue Apr 21

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.

Common errors

```
nodenv: command not found
```
cause 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.
```
cause 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.
```
cause 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.

Warnings

gotcha Overriding 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.
gotcha Committing `.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.
gotcha Incorrectly 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.
breaking Older 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.

Install

npm install node-env-run npm
yarn add node-env-run yarn
pnpm add node-env-run pnpm

Imports

nodenv (CLI Executable)
wrong:
```
import { nodenv } from 'node-env-run'
```
correct:
```
nodenv ./my-script.js
```
`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)
wrong:
```
npx nodenv ./my-script.js
```
correct:
```
npx node-env-run ./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
wrong:
```
import { EnvRunOptions } from 'node-env-run';
```
correct:
```
import type { 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.

Quickstart

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

view raw JSON →