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

Status:

This micro-lib allows you to provide a script which sets an environment using unix style and have it work on windows too

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 spawn) is:

webpack --config build/webpack.config.js

The NODE_ENV environment variable will be set by cross-env

Why?

Windows will choke when you set environment variables with NODE_ENV=production like that. This makes it so you can have a single command without worrying about setting the environment variable properly for the platform. Just set it like you would if it's running on a unix system, and cross-env will take care of setting it properly.

Known limitations

If you plan to do something like this:

cross-env FOO=bar && echo $FOO

And expect it to output bar you're going to be sad, for two reasons:

1. Technically, those will run as two separate commands, so even though FOO will properly be set to bar in the first command, the echo $FOO will not.
2. When echo $FOO runs, the $FOO variable is replaced with the variable value, before it's even passed to cross-env (though, as indicated in #1, that doesn't happen anyway)

The main use case for this package is to simply run another script which will (itself) respond to the environment variable. These limitations are not a problem in that scenario (like in the example).

Related Projects

env-cmd - Reads environment variables from a file instead

LICENSE

MIT