{"id":16139,"library":"node-env-run","title":"Node Environment Run","description":"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.","status":"active","version":"4.0.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/dkundel/node-env-run","tags":["javascript","dotenv","environment","variables","env",".env","config","settings","typescript"],"install":[{"cmd":"npm install node-env-run","lang":"bash","label":"npm"},{"cmd":"yarn add node-env-run","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-env-run","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for parsing `.env` files.","package":"dotenv","optional":false}],"imports":[{"note":"`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.","wrong":"import { nodenv } from 'node-env-run'","symbol":"nodenv (CLI Executable)","correct":"nodenv ./my-script.js"},{"note":"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.","wrong":"npx nodenv ./my-script.js","symbol":"node-env-run (npx usage)","correct":"npx node-env-run ./my-script.js"},{"note":"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.","wrong":"import { EnvRunOptions } from 'node-env-run';","symbol":"TypeScript Types","correct":"import type { EnvRunOptions } from 'node-env-run';"}],"quickstart":{"code":"// package.json\n{\n  \"name\": \"my-app\",\n  \"version\": \"1.0.0\",\n  \"scripts\": {\n    \"start\": \"nodenv .\"\n  }\n}\n\n// .env\nHELLO_MESSAGE=\"Hello from .env!\"\nPORT=3000\n\n// index.js (main script)\nconsole.log(`Loading application on port ${process.env.PORT ?? 'unknown'}.`);\nconsole.log(process.env.HELLO_MESSAGE ?? 'No message loaded.');\n\n// To run:\n// 1. npm install node-env-run --save-dev\n// 2. npm run start","lang":"typescript","description":"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."},"warnings":[{"fix":"To explicitly override existing variables, use the `--force` or `-f` flag: `nodenv --force .` This should be used cautiously, especially in shared environments.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<4.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","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.","error":"nodenv: command not found"},{"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`.","cause":"The `.env` file either wasn't found, was misconfigured, or the environment variable was not correctly defined within it.","error":"TypeError: Cannot read properties of undefined (reading 'SOME_ENV_VAR')` or similar errors indicating missing environment variables at runtime."},{"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.","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.","error":"(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."}],"ecosystem":"npm"}