cross-env

by kentcdodds

kentcdodds / cross-env

πŸ”€ Cross platform setting of environment scripts

5.1K Stars 204 Forks Last release: 8 months ago (v7.0.2) MIT License 110 Commits 44 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

cross-env πŸ”€

Run scripts that set and use environment variables across platforms


Travis Build Status AppVeyor Build Status Code Coverage version MIT License

All Contributors PRs Welcome Code of Conduct downloads

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

WARNING! Make sure that when you're installing packages that you spell things correctly to avoid mistakenly installing malware

NOTE : Version 7 of cross-env only supports Node.js 10 and higher, to use it on Node.js 8 or lower install version 6

npm install --save-dev [email protected]

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 set multiple environment variables at a time:

{
  "scripts": {
    "build": "cross-env FIRST_ENV=one SECOND_ENV=two node ./my-program"
  }
}

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": "cross-env-shell \"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. It also means that you can use
$GREET
env var syntax even on Windows which would usually require it to be
%GREET%
.

If you precede a dollar sign with an odd number of backslashes the expression statement will not be replaced. Note that this means backslashes after the JSON string escaping took place.

"FOO=\\$BAR"
will not be replaced.
"FOO=\\\\$BAR"
will be replaced though.

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 you 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
.

On Windows you need to use

cross-env-shell
, if you want to handle signal events inside of your program. A common case for that is when you want to capture a
SIGINT
event invoked by pressing
Ctrl + C
on the command-line interface.

Windows Issues

Please note that

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

Inspiration

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

Other Solutions

  • env-cmd
    - Reads environment variables from a file instead
  • @naholyr/cross-env
    -
    cross-env
    with support for setting default values

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

πŸ’» ⚠️

Sven

πŸ’» πŸ“– πŸ’‘ ⚠️

D. NicolΓ‘s Lopez Zelaya

πŸ’»

Johan Hernandez

πŸ’»

Jordan Nielson

πŸ› πŸ’» ⚠️

Jason Cooke

πŸ“–

bibo5088

πŸ’»

Eric Berry

πŸ”

MichaΓ«l De Boey

πŸ’»

Lauri Eskola

πŸ“–

devuxer

πŸ“–

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.