cross-env π
Run scripts that set and use environment variables across platforms
[![Travis Build Status][build-badge]][build]
[![AppVeyor Build Status][win-build-badge]][win-build]
[![Code Coverage][coverage-badge]][coverage]
[![Dependencies][dependencyci-badge]][dependencyci]
[![version][version-badge]][package]
[![node-version][node-version-badge]][node]
[![downloads][downloads-badge]][npm-stat]
[![MIT License][license-badge]][LICENSE]
[](#contributors)
[![PRs Welcome][prs-badge]][prs]
[![Donate][donate-badge]][donate]
[![Code of Conduct][coc-badge]][coc]
[![Roadmap][roadmap-badge]][roadmap]
[![Examples][examples-badge]][examples]
[![Watch on GitHub][github-watch-badge]][github-watch]
[![Star on GitHub][github-star-badge]][github-star]
[![Tweet][twitter-badge]][twitter]
## 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][win-bash],
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][npm] which is bundled with [node][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][malware]
## Usage
I use this in my npm scripts:
```json
{
"scripts": {
"build": "cross-env NODE_ENV=production webpack --config build/webpack.config.js"
}
}
```
Ultimately, the command that is executed (using [`cross-spawn`][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:
```json
{
"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:
```json
{
"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`][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`.
```json
{
"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](https://nodejs.org/api/process.html#process_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 leaverage that, then you need to update your
`.npmrc` to set the `script-shell` to powershell.
[Learn more here](https://github.com/kentcdodds/cross-env/issues/192#issuecomment-513341729).
## Inspiration
I originally created this to solve a problem I was having with my npm scripts in
[angular-formly][angular-formly]. This made contributing to the project
much easier for Windows users.
## Other Solutions
- [`env-cmd`](https://github.com/toddbluhm/env-cmd) - Reads environment variables from a file instead
- [`@naholyr/cross-env`](https://www.npmjs.com/package/@naholyr/cross-env) - `cross-env` with support for setting default values
## Contributors
Thanks goes to these people ([emoji key][emojis]):
| [
Kent C. Dodds](https://kentcdodds.com)
[π»](https://github.com/kentcdodds/cross-env/commits?author=kentcdodds "Code") [π](https://github.com/kentcdodds/cross-env/commits?author=kentcdodds "Documentation") [π](#infra-kentcdodds "Infrastructure (Hosting, Build-Tools, etc)") [β οΈ](https://github.com/kentcdodds/cross-env/commits?author=kentcdodds "Tests") | [
Ya Zhuang ](https://zhuangya.me)
[π](#plugin-zhuangya "Plugin/utility libraries") [π](https://github.com/kentcdodds/cross-env/commits?author=zhuangya "Documentation") | [
James Harris](https://wopian.me)
[π](https://github.com/kentcdodds/cross-env/commits?author=wopian "Documentation") | [
compumike08](https://github.com/compumike08)
[π](https://github.com/kentcdodds/cross-env/issues?q=author%3Acompumike08 "Bug reports") [π](https://github.com/kentcdodds/cross-env/commits?author=compumike08 "Documentation") [β οΈ](https://github.com/kentcdodds/cross-env/commits?author=compumike08 "Tests") | [
Daniel RodrΓguez Rivero](https://github.com/danielo515)
[π](https://github.com/kentcdodds/cross-env/issues?q=author%3Adanielo515 "Bug reports") [π»](https://github.com/kentcdodds/cross-env/commits?author=danielo515 "Code") [π](https://github.com/kentcdodds/cross-env/commits?author=danielo515 "Documentation") | [
Jonas Keinholz](https://github.com/inyono)
[π](https://github.com/kentcdodds/cross-env/issues?q=author%3Ainyono "Bug reports") [π»](https://github.com/kentcdodds/cross-env/commits?author=inyono "Code") [β οΈ](https://github.com/kentcdodds/cross-env/commits?author=inyono "Tests") | [
Hugo Wood](https://github.com/hgwood)
[π](https://github.com/kentcdodds/cross-env/issues?q=author%3Ahgwood "Bug reports") [π»](https://github.com/kentcdodds/cross-env/commits?author=hgwood "Code") [β οΈ](https://github.com/kentcdodds/cross-env/commits?author=hgwood "Tests") |
| :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| [
Thiebaud Thomas](https://github.com/thomasthiebaud)
[π](https://github.com/kentcdodds/cross-env/issues?q=author%3Athomasthiebaud "Bug reports") [π»](https://github.com/kentcdodds/cross-env/commits?author=thomasthiebaud "Code") [β οΈ](https://github.com/kentcdodds/cross-env/commits?author=thomasthiebaud "Tests") | [
Daniel Rey LΓ³pez](https://daniel.blog)
[π»](https://github.com/kentcdodds/cross-env/commits?author=DanReyLop "Code") [β οΈ](https://github.com/kentcdodds/cross-env/commits?author=DanReyLop "Tests") | [
Amila Welihinda](http://amilajack.com)
[π](#infra-amilajack "Infrastructure (Hosting, Build-Tools, etc)") | [
Paul Betts](https://twitter.com/paulcbetts)
[π](https://github.com/kentcdodds/cross-env/issues?q=author%3Apaulcbetts "Bug reports") [π»](https://github.com/kentcdodds/cross-env/commits?author=paulcbetts "Code") | [
Turner Hayes](https://github.com/turnerhayes)
[π](https://github.com/kentcdodds/cross-env/issues?q=author%3Aturnerhayes "Bug reports") [π»](https://github.com/kentcdodds/cross-env/commits?author=turnerhayes "Code") [β οΈ](https://github.com/kentcdodds/cross-env/commits?author=turnerhayes "Tests") | [
Suhas Karanth](https://github.com/sudo-suhas)
[π»](https://github.com/kentcdodds/cross-env/commits?author=sudo-suhas "Code") [β οΈ](https://github.com/kentcdodds/cross-env/commits?author=sudo-suhas "Tests") | [
Sven](https://github.com/sventschui)
[π»](https://github.com/kentcdodds/cross-env/commits?author=sventschui "Code") [π](https://github.com/kentcdodds/cross-env/commits?author=sventschui "Documentation") [π‘](#example-sventschui "Examples") [β οΈ](https://github.com/kentcdodds/cross-env/commits?author=sventschui "Tests") |
| [
D. NicolΓ‘s Lopez Zelaya](https://github.com/NicoZelaya)
[π»](https://github.com/kentcdodds/cross-env/commits?author=NicoZelaya "Code") | [
Johan Hernandez](http://bithavoc.io)
[π»](https://github.com/kentcdodds/cross-env/commits?author=bithavoc "Code") | [
Jordan Nielson](https://github.com/jnielson94)
[π](https://github.com/kentcdodds/cross-env/issues?q=author%3Ajnielson94 "Bug reports") [π»](https://github.com/kentcdodds/cross-env/commits?author=jnielson94 "Code") [β οΈ](https://github.com/kentcdodds/cross-env/commits?author=jnielson94 "Tests") | [
Jason Cooke](https://nz.linkedin.com/in/jsonc11)
[π](https://github.com/kentcdodds/cross-env/commits?author=Jason-Cooke "Documentation") | [
bibo5088](https://github.com/bibo5088)
[π»](https://github.com/kentcdodds/cross-env/commits?author=bibo5088 "Code") |
This project follows the [all-contributors][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
[npm]: https://www.npmjs.com/
[node]: https://nodejs.org
[build-badge]: https://img.shields.io/travis/kentcdodds/cross-env.svg?style=flat-square
[build]: https://travis-ci.org/kentcdodds/cross-env
[win-build-badge]: https://img.shields.io/appveyor/ci/kentcdodds/cross-env.svg?style=flat-square
[win-build]: https://ci.appveyor.com/project/kentcdodds/cross-env
[coverage-badge]: https://img.shields.io/codecov/c/github/kentcdodds/cross-env.svg?style=flat-square
[coverage]: https://codecov.io/github/kentcdodds/cross-env
[dependencyci-badge]: https://dependencyci.com/github/kentcdodds/cross-env/badge?style=flat-square
[dependencyci]: https://dependencyci.com/github/kentcdodds/cross-env
[version-badge]: https://img.shields.io/npm/v/cross-env.svg?style=flat-square
[package]: https://www.npmjs.com/package/cross-env
[node-version-badge]: https://img.shields.io/badge/node-%3E%3D%204.0-orange.svg?style=flat-square
[downloads-badge]: https://img.shields.io/npm/dm/cross-env.svg?style=flat-square
[npm-stat]: http://npm-stat.com/charts.html?package=cross-env&from=2016-04-01
[license-badge]: https://img.shields.io/npm/l/cross-env.svg?style=flat-square
[license]: https://github.com/kentcdodds/cross-env/blob/master/other/LICENSE
[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
[prs]: http://makeapullrequest.com
[donate-badge]: https://img.shields.io/badge/$-support-green.svg?style=flat-square
[donate]: http://kcd.im/donate
[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
[coc]: https://github.com/kentcdodds/cross-env/blob/master/other/CODE_OF_CONDUCT.md
[roadmap-badge]: https://img.shields.io/badge/%F0%9F%93%94-roadmap-CD9523.svg?style=flat-square
[roadmap]: https://github.com/kentcdodds/cross-env/blob/master/other/ROADMAP.md
[examples-badge]: https://img.shields.io/badge/%F0%9F%92%A1-examples-8C8E93.svg?style=flat-square
[examples]: https://github.com/kentcdodds/cross-env/blob/master/other/EXAMPLES.md
[github-watch-badge]: https://img.shields.io/github/watchers/kentcdodds/cross-env.svg?style=social
[github-watch]: https://github.com/kentcdodds/cross-env/watchers
[github-star-badge]: https://img.shields.io/github/stars/kentcdodds/cross-env.svg?style=social
[github-star]: https://github.com/kentcdodds/cross-env/stargazers
[twitter]: https://twitter.com/intent/tweet?text=Check%20out%20cross-env!%20https://github.com/kentcdodds/cross-env%20%F0%9F%91%8D
[twitter-badge]: https://img.shields.io/twitter/url/https/github.com/kentcdodds/cross-env.svg?style=social
[emojis]: https://github.com/kentcdodds/all-contributors#emoji-key
[all-contributors]: https://github.com/kentcdodds/all-contributors
[win-bash]: https://msdn.microsoft.com/en-us/commandline/wsl/about
[angular-formly]: https://github.com/formly-js/angular-formly
[cross-spawn]: https://www.npmjs.com/package/cross-spawn
[ts-loader]: https://www.npmjs.com/package/ts-loader
[malware]: http://blog.npmjs.org/post/163723642530/crossenv-malware-on-the-npm-registry