cross-env

What is cross-env?

The cross-env npm package is a cross-platform solution for setting and using environment variables in scripts. It works well for both Windows and UNIX-based systems (like Linux and macOS), making it easier to write scripts that work across different environments without modification.

What are cross-env's main functionalities?

Setting environment variables

This feature allows you to set environment variables in your npm scripts. The code sample sets the NODE_ENV variable to 'production' before executing 'node app.js'.

cross-env NODE_ENV=production node app.js

Setting multiple environment variables

With cross-env, you can set multiple environment variables at once. The code sample sets both NODE_ENV and API_KEY before running 'node app.js'.

cross-env NODE_ENV=production API_KEY=12345 node app.js

Inline environment variable setting

You can use cross-env to set environment variables inline with your script execution. The code sample sets the GREETING variable and immediately runs a node command that logs the value of GREETING.

cross-env GREETING='Hello, World!' node -e "console.log(process.env.GREETING)"

Other packages similar to cross-env

env-cmd

env-cmd is a similar package that allows you to specify a file containing environment variable definitions. It's a bit different from cross-env because it doesn't set variables inline but rather reads them from a file.

dotenv

dotenv is another package that loads environment variables from a .env file into process.env. It's commonly used for development purposes and differs from cross-env in that it's not intended for setting variables directly in scripts.

dotenv-expand

dotenv-expand extends dotenv by allowing you to have environment variables that reference other environment variables within your .env file. It's more about expanding variables rather than setting them in scripts like cross-env.

README

cross-env

Run scripts that set and use environment variables across platforms

The problem

Most Windows command prompts will choke when you set environment variables with NODE_ENV=production like that. (The exception is Bash on Windows, which uses native Bash.) Similarly, there's a difference in how windows and POSIX commands utilize environment variables. With POSIX, you use: $ENV_VAR and on windows you use %ENV_VAR%.

This solution

cross-env makes it so you can have a single command without worrying about setting or using the environment variable properly for the platform. Just set it like you would if it's running on a POSIX system, and cross-env will take care of setting it properly.

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's devDependencies:

npm install --save-dev cross-env

Usage

I use this in my npm scripts:

{
  "scripts": {
    "build": "cross-env NODE_ENV=production webpack --config build/webpack.config.js"
  }
}

Ultimately, the command that is executed (using cross-spawn) is:

webpack --config build/webpack.config.js

The NODE_ENV environment variable will be set by cross-env

You can also split a command into several ones, or separate the environment variables declaration from the actual command execution. You can do it this way:

{
  "scripts": {
    "parentScript": "cross-env GREET=\"Joe\" npm run childScript",
    "childScript": "echo Hello $GREET"
  }
}

Where childScript holds the actual command to execute and parentScript sets the environment variables to use. Then instead of run the childScript you run the parent. This is quite useful for launching the same command with different env variables or when the environment variables are too long to have everything in one line.

Lastly, if you want to pass a JSON string (e.g., when using ts-loader), you can do as follows:

{
  "scripts": {
    "test": "cross-env TS_NODE_COMPILER_OPTIONS={\\\"module\\\":\\\"commonjs\\\"} node some_file.test.ts"
  }
}

Pay special attention to the triple backslash (\\\) before the double quotes (") and the absence of single quotes ('). Both of these conditions have to be met in order to work both on Windows and UNIX.

cross-env vs cross-env-shell

The cross-env module exposes two bins: cross-env and cross-env-shell. The first one executes commands using cross-spawn, while the second one uses the shell option from Node's spawn.

The main use case for cross-env-shell is when your need an environment variable to be set across an entire inline shell script, rather than just one command.

For example, if you want to have the environment variable apply to several commands in series then you will need to wrap those in quotes and use cross-env-shell instead of cross-env.

{
  "scripts": {
    "greet": "cross-env-shell GREETING=Hi NAME=Joe \"echo $GREETING && echo $NAME\""
  }
}

The rule of thumb is: if you want to pass to cross-env a command that contains special shell characters that you want interpreted, then use cross-env-shell. Otherwise stick to cross-env.

Inspiration

I originally created this to solve a problem I was having with my npm scripts in angular-formly. This made it made contributing to the project much easier for windows users.

Other Solutions

• env-cmd - Reads environment variables from a file instead

Contributors

Thanks goes to these people (emoji key):

Kent C. Dodds 💻 📖 🚇 ⚠️	Ya Zhuang 🔌 📖	James Harris 📖	compumike08 🐛 📖 ⚠️	Daniel Rodríguez Rivero 🐛 💻 📖	Jonas Keinholz 🐛 💻 ⚠️	Hugo Wood 🐛 💻 ⚠️
Thiebaud Thomas 🐛 💻 ⚠️	Daniel Rey López 💻 ⚠️	Amila Welihinda 🚇	Paul Betts 🐛 💻	Turner Hayes 🐛 💻 ⚠️	Suhas Karanth 💻 ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!

Note: this was added late into the project. If you've contributed to this project in any way, please make a pull request to add yourself to the list by following the instructions in the CONTRIBUTING.md

LICENSE

MIT