You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

219 lines
16 KiB

4 years ago
  1. <div align="center">
  2. <h1>cross-env 🔀</h1>
  3. Run scripts that set and use environment variables across platforms
  4. </div>
  5. <hr />
  6. [![Travis Build Status][build-badge]][build]
  7. [![AppVeyor Build Status][win-build-badge]][win-build]
  8. [![Code Coverage][coverage-badge]][coverage]
  9. [![Dependencies][dependencyci-badge]][dependencyci]
  10. [![version][version-badge]][package]
  11. [![node-version][node-version-badge]][node]
  12. [![downloads][downloads-badge]][npm-stat]
  13. [![MIT License][license-badge]][LICENSE]
  14. [![All Contributors](https://img.shields.io/badge/all_contributors-19-orange.svg?style=flat-square)](#contributors)
  15. [![PRs Welcome][prs-badge]][prs]
  16. [![Donate][donate-badge]][donate]
  17. [![Code of Conduct][coc-badge]][coc]
  18. [![Roadmap][roadmap-badge]][roadmap]
  19. [![Examples][examples-badge]][examples]
  20. [![Watch on GitHub][github-watch-badge]][github-watch]
  21. [![Star on GitHub][github-star-badge]][github-star]
  22. [![Tweet][twitter-badge]][twitter]
  23. ## The problem
  24. Most Windows command prompts will choke when you set environment variables with
  25. `NODE_ENV=production` like that. (The exception is [Bash on Windows][win-bash],
  26. which uses native Bash.) Similarly, there's a difference in how windows and
  27. POSIX commands utilize environment variables. With POSIX, you use: `$ENV_VAR`
  28. and on windows you use `%ENV_VAR%`.
  29. ## This solution
  30. `cross-env` makes it so you can have a single command without worrying about
  31. setting or using the environment variable properly for the platform. Just set it
  32. like you would if it's running on a POSIX system, and `cross-env` will take care
  33. of setting it properly.
  34. ## Installation
  35. This module is distributed via [npm][npm] which is bundled with [node][node] and
  36. should be installed as one of your project's `devDependencies`:
  37. ```
  38. npm install --save-dev cross-env
  39. ```
  40. > WARNING! Make sure that when you're installing packages that you spell things
  41. > correctly to avoid [mistakenly installing malware][malware]
  42. ## Usage
  43. I use this in my npm scripts:
  44. ```json
  45. {
  46. "scripts": {
  47. "build": "cross-env NODE_ENV=production webpack --config build/webpack.config.js"
  48. }
  49. }
  50. ```
  51. Ultimately, the command that is executed (using [`cross-spawn`][cross-spawn])
  52. is:
  53. ```
  54. webpack --config build/webpack.config.js
  55. ```
  56. The `NODE_ENV` environment variable will be set by `cross-env`
  57. You can also split a command into several ones, or separate the environment
  58. variables declaration from the actual command execution. You can do it this way:
  59. ```json
  60. {
  61. "scripts": {
  62. "parentScript": "cross-env GREET=\"Joe\" npm run childScript",
  63. "childScript": "cross-env-shell \"echo Hello $GREET\""
  64. }
  65. }
  66. ```
  67. Where `childScript` holds the actual command to execute and `parentScript` sets
  68. the environment variables to use. Then instead of run the childScript you run
  69. the parent. This is quite useful for launching the same command with different
  70. env variables or when the environment variables are too long to have everything
  71. in one line. It also means that you can use `$GREET` env var syntax even on
  72. Windows which would usually require it to be `%GREET%`.
  73. 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.
  74. Lastly, if you want to pass a JSON string (e.g., when using [ts-loader]), you can do as follows:
  75. ```json
  76. {
  77. "scripts": {
  78. "test": "cross-env TS_NODE_COMPILER_OPTIONS={\\\"module\\\":\\\"commonjs\\\"} node some_file.test.ts"
  79. }
  80. }
  81. ```
  82. Pay special attention to the **triple backslash** `(\\\)` **before** the **double quotes** `(")` and the **absence** of **single quotes** `(')`.
  83. Both of these conditions have to be met in order to work both on Windows and UNIX.
  84. ## `cross-env` vs `cross-env-shell`
  85. The `cross-env` module exposes two bins: `cross-env` and `cross-env-shell`. The
  86. first one executes commands using [`cross-spawn`][cross-spawn], while the
  87. second one uses the `shell` option from Node's `spawn`.
  88. The main use case for `cross-env-shell` is when you need an environment
  89. variable to be set across an entire inline shell script, rather than just one
  90. command.
  91. For example, if you want to have the environment variable apply to several
  92. commands in series then you will need to wrap those in quotes and use
  93. `cross-env-shell` instead of `cross-env`.
  94. ```json
  95. {
  96. "scripts": {
  97. "greet": "cross-env-shell GREETING=Hi NAME=Joe \"echo $GREETING && echo $NAME\""
  98. }
  99. }
  100. ```
  101. The rule of thumb is: if you want to pass to `cross-env` a command that
  102. contains special shell characters *that you want interpreted*, then use
  103. `cross-env-shell`. Otherwise stick to `cross-env`.
  104. 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.
  105. ## Windows Issues
  106. Please note that `npm` uses `cmd` by default and that doesn't support command
  107. substitution, so if you want to leaverage that, then you need to update your
  108. `.npmrc` to set the `script-shell` to powershell.
  109. [Learn more here](https://github.com/kentcdodds/cross-env/issues/192#issuecomment-513341729).
  110. ## Inspiration
  111. I originally created this to solve a problem I was having with my npm scripts in
  112. [angular-formly][angular-formly]. This made contributing to the project
  113. much easier for Windows users.
  114. ## Other Solutions
  115. - [`env-cmd`](https://github.com/toddbluhm/env-cmd) - Reads environment variables from a file instead
  116. - [`@naholyr/cross-env`](https://www.npmjs.com/package/@naholyr/cross-env) - `cross-env` with support for setting default values
  117. ## Contributors
  118. Thanks goes to these people ([emoji key][emojis]):
  119. <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
  120. <!-- prettier-ignore -->
  121. | [<img src="https://avatars.githubusercontent.com/u/1500684?v=3" width="100px;"/><br /><sub><b>Kent C. Dodds</b></sub>](https://kentcdodds.com)<br />[💻](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") | [<img src="https://avatars1.githubusercontent.com/u/499038?v=3" width="100px;"/><br /><sub><b>Ya Zhuang </b></sub>](https://zhuangya.me)<br />[🔌](#plugin-zhuangya "Plugin/utility libraries") [📖](https://github.com/kentcdodds/cross-env/commits?author=zhuangya "Documentation") | [<img src="https://avatars3.githubusercontent.com/u/3440094?v=3" width="100px;"/><br /><sub><b>James Harris</b></sub>](https://wopian.me)<br />[📖](https://github.com/kentcdodds/cross-env/commits?author=wopian "Documentation") | [<img src="https://avatars1.githubusercontent.com/u/8941730?v=3" width="100px;"/><br /><sub><b>compumike08</b></sub>](https://github.com/compumike08)<br />[🐛](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") | [<img src="https://avatars1.githubusercontent.com/u/2270425?v=3" width="100px;"/><br /><sub><b>Daniel Rodríguez Rivero</b></sub>](https://github.com/danielo515)<br />[🐛](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") | [<img src="https://avatars2.githubusercontent.com/u/1508477?v=3" width="100px;"/><br /><sub><b>Jonas Keinholz</b></sub>](https://github.com/inyono)<br />[🐛](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") | [<img src="https://avatars3.githubusercontent.com/u/1656170?v=3" width="100px;"/><br /><sub><b>Hugo Wood</b></sub>](https://github.com/hgwood)<br />[🐛](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") |
  122. | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
  123. | [<img src="https://avatars0.githubusercontent.com/u/3715715?v=3" width="100px;"/><br /><sub><b>Thiebaud Thomas</b></sub>](https://github.com/thomasthiebaud)<br />[🐛](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") | [<img src="https://avatars1.githubusercontent.com/u/1715800?v=3" width="100px;"/><br /><sub><b>Daniel Rey López</b></sub>](https://daniel.blog)<br />[💻](https://github.com/kentcdodds/cross-env/commits?author=DanReyLop "Code") [⚠️](https://github.com/kentcdodds/cross-env/commits?author=DanReyLop "Tests") | [<img src="https://avatars2.githubusercontent.com/u/6374832?v=3" width="100px;"/><br /><sub><b>Amila Welihinda</b></sub>](http://amilajack.com)<br />[🚇](#infra-amilajack "Infrastructure (Hosting, Build-Tools, etc)") | [<img src="https://avatars1.githubusercontent.com/u/1396?v=3" width="100px;"/><br /><sub><b>Paul Betts</b></sub>](https://twitter.com/paulcbetts)<br />[🐛](https://github.com/kentcdodds/cross-env/issues?q=author%3Apaulcbetts "Bug reports") [💻](https://github.com/kentcdodds/cross-env/commits?author=paulcbetts "Code") | [<img src="https://avatars1.githubusercontent.com/u/6371670?v=3" width="100px;"/><br /><sub><b>Turner Hayes</b></sub>](https://github.com/turnerhayes)<br />[🐛](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") | [<img src="https://avatars2.githubusercontent.com/u/22251956?v=4" width="100px;"/><br /><sub><b>Suhas Karanth</b></sub>](https://github.com/sudo-suhas)<br />[💻](https://github.com/kentcdodds/cross-env/commits?author=sudo-suhas "Code") [⚠️](https://github.com/kentcdodds/cross-env/commits?author=sudo-suhas "Tests") | [<img src="https://avatars3.githubusercontent.com/u/512692?v=4" width="100px;"/><br /><sub><b>Sven</b></sub>](https://github.com/sventschui)<br />[💻](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") |
  124. | [<img src="https://avatars0.githubusercontent.com/u/5522668?v=4" width="100px;"/><br /><sub><b>D. Nicolás Lopez Zelaya</b></sub>](https://github.com/NicoZelaya)<br />[💻](https://github.com/kentcdodds/cross-env/commits?author=NicoZelaya "Code") | [<img src="https://avatars3.githubusercontent.com/u/219289?v=4" width="100px;"/><br /><sub><b>Johan Hernandez</b></sub>](http://bithavoc.io)<br />[💻](https://github.com/kentcdodds/cross-env/commits?author=bithavoc "Code") | [<img src="https://avatars3.githubusercontent.com/u/13559161?v=4" width="100px;"/><br /><sub><b>Jordan Nielson</b></sub>](https://github.com/jnielson94)<br />[🐛](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") | [<img src="https://avatars0.githubusercontent.com/u/5185660?v=4" width="100px;"/><br /><sub><b>Jason Cooke</b></sub>](https://nz.linkedin.com/in/jsonc11)<br />[📖](https://github.com/kentcdodds/cross-env/commits?author=Jason-Cooke "Documentation") | [<img src="https://avatars0.githubusercontent.com/u/17709887?v=4" width="100px;"/><br /><sub><b>bibo5088</b></sub>](https://github.com/bibo5088)<br />[💻](https://github.com/kentcdodds/cross-env/commits?author=bibo5088 "Code") |
  125. <!-- ALL-CONTRIBUTORS-LIST:END -->
  126. This project follows the [all-contributors][all-contributors] specification. Contributions of any kind welcome!
  127. > Note: this was added late into the project. If you've contributed to this
  128. > project in any way, please make a pull request to add yourself to the list
  129. > by following the instructions in the `CONTRIBUTING.md`
  130. ## LICENSE
  131. MIT
  132. [npm]: https://www.npmjs.com/
  133. [node]: https://nodejs.org
  134. [build-badge]: https://img.shields.io/travis/kentcdodds/cross-env.svg?style=flat-square
  135. [build]: https://travis-ci.org/kentcdodds/cross-env
  136. [win-build-badge]: https://img.shields.io/appveyor/ci/kentcdodds/cross-env.svg?style=flat-square
  137. [win-build]: https://ci.appveyor.com/project/kentcdodds/cross-env
  138. [coverage-badge]: https://img.shields.io/codecov/c/github/kentcdodds/cross-env.svg?style=flat-square
  139. [coverage]: https://codecov.io/github/kentcdodds/cross-env
  140. [dependencyci-badge]: https://dependencyci.com/github/kentcdodds/cross-env/badge?style=flat-square
  141. [dependencyci]: https://dependencyci.com/github/kentcdodds/cross-env
  142. [version-badge]: https://img.shields.io/npm/v/cross-env.svg?style=flat-square
  143. [package]: https://www.npmjs.com/package/cross-env
  144. [node-version-badge]: https://img.shields.io/badge/node-%3E%3D%204.0-orange.svg?style=flat-square
  145. [downloads-badge]: https://img.shields.io/npm/dm/cross-env.svg?style=flat-square
  146. [npm-stat]: http://npm-stat.com/charts.html?package=cross-env&from=2016-04-01
  147. [license-badge]: https://img.shields.io/npm/l/cross-env.svg?style=flat-square
  148. [license]: https://github.com/kentcdodds/cross-env/blob/master/other/LICENSE
  149. [prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
  150. [prs]: http://makeapullrequest.com
  151. [donate-badge]: https://img.shields.io/badge/$-support-green.svg?style=flat-square
  152. [donate]: http://kcd.im/donate
  153. [coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
  154. [coc]: https://github.com/kentcdodds/cross-env/blob/master/other/CODE_OF_CONDUCT.md
  155. [roadmap-badge]: https://img.shields.io/badge/%F0%9F%93%94-roadmap-CD9523.svg?style=flat-square
  156. [roadmap]: https://github.com/kentcdodds/cross-env/blob/master/other/ROADMAP.md
  157. [examples-badge]: https://img.shields.io/badge/%F0%9F%92%A1-examples-8C8E93.svg?style=flat-square
  158. [examples]: https://github.com/kentcdodds/cross-env/blob/master/other/EXAMPLES.md
  159. [github-watch-badge]: https://img.shields.io/github/watchers/kentcdodds/cross-env.svg?style=social
  160. [github-watch]: https://github.com/kentcdodds/cross-env/watchers
  161. [github-star-badge]: https://img.shields.io/github/stars/kentcdodds/cross-env.svg?style=social
  162. [github-star]: https://github.com/kentcdodds/cross-env/stargazers
  163. [twitter]: https://twitter.com/intent/tweet?text=Check%20out%20cross-env!%20https://github.com/kentcdodds/cross-env%20%F0%9F%91%8D
  164. [twitter-badge]: https://img.shields.io/twitter/url/https/github.com/kentcdodds/cross-env.svg?style=social
  165. [emojis]: https://github.com/kentcdodds/all-contributors#emoji-key
  166. [all-contributors]: https://github.com/kentcdodds/all-contributors
  167. [win-bash]: https://msdn.microsoft.com/en-us/commandline/wsl/about
  168. [angular-formly]: https://github.com/formly-js/angular-formly
  169. [cross-spawn]: https://www.npmjs.com/package/cross-spawn
  170. [ts-loader]: https://www.npmjs.com/package/ts-loader
  171. [malware]: http://blog.npmjs.org/post/163723642530/crossenv-malware-on-the-npm-registry