• About
• Installation
• Usage
• noxenv vs noxenv-shell
• Windows Users
• Troubleshooting
  • Error: 'noxenv' is not recognized as an internal or external command
• Contributors ✨

About

noxenv is a NodeJS package which allows you to pass environment variables to your project, including run commands within your package.json.

Most Windows-based command prompts / terminals will have issues when you attempt to set env variables utilizing NODE_ENV=production; unless you are using [Bash on Windows][win-bash]. Coupled with the issue that Windows and *NIX have different ways of utilizing env variables such as:

• Windows: %ENV_VAR%
• *NIX: $ENV_VAR

noxenv gives you the ability to have a single command at your disposal; without the hassle of worrying about different platforms. Specify your env variable as you would on *nix, and noxenv will take care of the conversion for Windows users.

[!NOTE] noxenv only supports Node.js v16 and higher. As of May 2025, NodeJS v15 has been sunset.

Installation

This module is distributed via [npm][npm] which is bundled with [node][node]. To utilize this moduke, add it to your project's package.json -> devDependencies:

"devDependencies": {
    "@aetherinox/noxenv": "^1.1.0"
},

To install it via the npm command-line as a devDependency:

npm i --save-dev @aetherinox/noxenv

Usage

Some examples have been provided below to show various ways of using noxenv:

{
    "scripts": {
        "build": "noxenv NODE_ENV=production webpack --config build/webpack.config.js",
        "build-rollup": "noxenv NODE_ENV=production rollup -c",
        "development": "noxenv NODE_ENV=development npm start",
        "production": "noxenv NODE_ENV=production SERVER_IP=http://127.0.0.1 npm start",
        "test": "noxenv BABEL_ENV=test jest test/app",
        "start-dev": "noxenv NODE_ENV=development PORT_ENV=2350 npm run build && node dist/src/main.js",
        "openssl-legacy": "noxenv NODE_OPTIONS=\"--openssl-legacy-provider\" tsc -p tsconfig.json"
    }
}

Inside your module, you can call these env variables with something similar to the below example:

const TEST = { api: "f4dcc990-f8f7-4343-b852-a2065b4445d5" };
const PROD = { api: "d1ac1eb8-7194-4095-8976-04be09378611" };

let target;
if (process.env.BABEL_ENV === "development") {
    target = TEST;
} else if (process.env.BABEL_ENV === "production") {
    target = PROD;
}

console.log(`Running ${process.env.BABEL_ENV} mode; API key is ${target}`);

In the above example, variables such as BABEL_ENV will be set by noxenv. You can also set multiple environment variables at a time:

{
    "scripts": {
        "release-beta": "noxenv RELEASE=beta ENV=dev PORT=7732 npm run release && npm run start",
    }
}

Additionally; you can split the command into several actions, or separate the env variable declarations from the actual command execution; note the following example:

{
    "scripts": {
        "parent": "noxenv USER_NAME=\"Joe\" npm run child",
        "child": "noxenv-shell \"echo Hello $USER_NAME\""
    }
}

In the above example, child stores the actual command to execute, and parent sets the env variable that is going to be used. In this case, Joe is the user we want to say hello to, so we store Joe's name in within the env variable USER_NAME, and then at the end of parent, we call child which does the actual greeting.

This means that you only need to call parent, and both will be ran. Additionally, it also means that you can also call the env variable using $USER_NAME on Windows, even though the typical Windows syntax is %USER_NAME%.

If you wish to pass a JSON string (such as when using [ts-loader]), you may do the following:

{
    "scripts": {
        "test": "noxenv TS_NODE_COMPILER_OPTIONS={\\\"module\\\":\\\"commonjs\\\"} mocha --config ./test.js"
    }
}

Take note of the triple backslashes (\\\) before double quotes (") and the absence of single quotes ('). This syntax is critical in order for the env var to work on both on Windows and *NIX.

noxenv vs noxenv-shell

noxenv provides two binary files: noxenv and noxenv-shell.

| Binary | Description | | --- | --- | | noxenv | Executes commands utilizing [cross-spawn][cross-spawn] | | noxenv-shell | Executes commands utilizing node's shell. Useful when you need an env var to be set across an entire shell script, rather than a single command. Also used when wanting to pass a command that contains special shell characters that you need interpreted |

If you want to have the env variable apply to several commands in a series, you will need to wrap them in quotes and use noxenv-shell, instead of noxenv.

{
    "scripts": {
        "salutation": "noxenv-shell SALUTATION=Howdy NAME=Aetherinox \"echo $SALUTATION && echo $NAME\""
    }
}

If you need to handle signal events within your project, use noxenv-shell. An example use for this is when you want to capture the SIGINT event invoked by pressing Ctrl + C within your command-line interface.

Windows Users

Note that npm uses cmd by default and doesn't support command substitution, so if you want to leverage that, then you need to update your .npmrc and set script-shell to powershell.

Troubleshooting

Review the following list of issues and corrective measures you can take to address the issues:

Error: 'noxenv' is not recognized as an internal or external command

If you get the following error when running a NodeJS script which utilizes noxenv:

'noxenv' is not recognized as an internal or external command,
operable program or batch file.

Ensure you install it first locally as a dev dependency:

npm i --save-dev @aetherinox/noxenv

Contributors ✨

We are always looking for contributors. If you feel that you can provide something useful to this project, then we'd love to review your suggestion. Before submitting your contribution, please review the following resources:

• Pull Request Procedure
• Contributor Policy

Want to help but can't write code?

• Review active questions by our community and answer the ones you know.

The following people have helped keep this project going: