1 | <div align="center">
|
2 | <h1>cross-env π</h1>
|
3 |
|
4 | Run scripts that set and use environment variables across platforms
|
5 |
|
6 | </div>
|
7 |
|
8 | <hr />
|
9 |
|
10 | [![Travis Build Status][build-badge]][build]
|
11 | [![AppVeyor Build Status][win-build-badge]][win-build]
|
12 | [![Code Coverage][coverage-badge]][coverage]
|
13 | [![version][version-badge]][package] [![MIT License][license-badge]][license]
|
14 |
|
15 | [![All Contributors](https://img.shields.io/badge/all_contributors-20-orange.svg?style=flat-square)](#contributors)
|
16 | [![PRs Welcome][prs-badge]][prs] [![Code of Conduct][coc-badge]][coc]
|
17 | [![downloads][downloads-badge]][npmtrends]
|
18 |
|
19 | ## The problem
|
20 |
|
21 | Most Windows command prompts will choke when you set environment variables with
|
22 | `NODE_ENV=production` like that. (The exception is [Bash on Windows][win-bash],
|
23 | which uses native Bash.) Similarly, there's a difference in how windows and
|
24 | POSIX commands utilize environment variables. With POSIX, you use: `$ENV_VAR`
|
25 | and on windows you use `%ENV_VAR%`.
|
26 |
|
27 | ## This solution
|
28 |
|
29 | `cross-env` makes it so you can have a single command without worrying about
|
30 | setting or using the environment variable properly for the platform. Just set it
|
31 | like you would if it's running on a POSIX system, and `cross-env` will take care
|
32 | of setting it properly.
|
33 |
|
34 |
|
35 |
|
36 |
|
37 | - [Installation](#installation)
|
38 | - [Usage](#usage)
|
39 | - [`cross-env` vs `cross-env-shell`](#cross-env-vs-cross-env-shell)
|
40 | - [Windows Issues](#windows-issues)
|
41 | - [Inspiration](#inspiration)
|
42 | - [Other Solutions](#other-solutions)
|
43 | - [Contributors](#contributors)
|
44 | - [LICENSE](#license)
|
45 |
|
46 |
|
47 |
|
48 | ## Installation
|
49 |
|
50 | This module is distributed via [npm][npm] which is bundled with [node][node] and
|
51 | should be installed as one of your project's `devDependencies`:
|
52 |
|
53 | ```
|
54 | npm install --save-dev cross-env
|
55 | ```
|
56 |
|
57 | > WARNING! Make sure that when you're installing packages that you spell things
|
58 | > correctly to avoid [mistakenly installing malware][malware]
|
59 |
|
60 | > NOTE : Version 7 of cross-env only supports Node.js 10 and higher, to use it on
|
61 | > Node.js 8 or lower install version 6 `npm install --save-dev cross-env@6`
|
62 |
|
63 | ## Usage
|
64 |
|
65 | I use this in my npm scripts:
|
66 |
|
67 | ```json
|
68 | {
|
69 | "scripts": {
|
70 | "build": "cross-env NODE_ENV=production webpack --config build/webpack.config.js"
|
71 | }
|
72 | }
|
73 | ```
|
74 |
|
75 | Ultimately, the command that is executed (using [`cross-spawn`][cross-spawn])
|
76 | is:
|
77 |
|
78 | ```
|
79 | webpack --config build/webpack.config.js
|
80 | ```
|
81 |
|
82 | The `NODE_ENV` environment variable will be set by `cross-env`
|
83 |
|
84 | You can also split a command into several ones, or separate the environment
|
85 | variables declaration from the actual command execution. You can do it this way:
|
86 |
|
87 | ```json
|
88 | {
|
89 | "scripts": {
|
90 | "parentScript": "cross-env GREET=\"Joe\" npm run childScript",
|
91 | "childScript": "cross-env-shell \"echo Hello $GREET\""
|
92 | }
|
93 | }
|
94 | ```
|
95 |
|
96 | Where `childScript` holds the actual command to execute and `parentScript` sets
|
97 | the environment variables to use. Then instead of run the childScript you run
|
98 | the parent. This is quite useful for launching the same command with different
|
99 | env variables or when the environment variables are too long to have everything
|
100 | in one line. It also means that you can use `$GREET` env var syntax even on
|
101 | Windows which would usually require it to be `%GREET%`.
|
102 |
|
103 | If you precede a dollar sign with an odd number of backslashes the expression
|
104 | statement will not be replaced. Note that this means backslashes after the JSON
|
105 | string escaping took place. `"FOO=\\$BAR"` will not be replaced.
|
106 | `"FOO=\\\\$BAR"` will be replaced though.
|
107 |
|
108 | Lastly, if you want to pass a JSON string (e.g., when using [ts-loader]), you
|
109 | can do as follows:
|
110 |
|
111 | ```json
|
112 | {
|
113 | "scripts": {
|
114 | "test": "cross-env TS_NODE_COMPILER_OPTIONS={\\\"module\\\":\\\"commonjs\\\"} node some_file.test.ts"
|
115 | }
|
116 | }
|
117 | ```
|
118 |
|
119 | Pay special attention to the **triple backslash** `(\\\)` **before** the
|
120 | **double quotes** `(")` and the **absence** of **single quotes** `(')`. Both of
|
121 | these conditions have to be met in order to work both on Windows and UNIX.
|
122 |
|
123 | ## `cross-env` vs `cross-env-shell`
|
124 |
|
125 | The `cross-env` module exposes two bins: `cross-env` and `cross-env-shell`. The
|
126 | first one executes commands using [`cross-spawn`][cross-spawn], while the second
|
127 | one uses the `shell` option from Node's `spawn`.
|
128 |
|
129 | The main use case for `cross-env-shell` is when you need an environment variable
|
130 | to be set across an entire inline shell script, rather than just one command.
|
131 |
|
132 | For example, if you want to have the environment variable apply to several
|
133 | commands in series then you will need to wrap those in quotes and use
|
134 | `cross-env-shell` instead of `cross-env`.
|
135 |
|
136 | ```json
|
137 | {
|
138 | "scripts": {
|
139 | "greet": "cross-env-shell GREETING=Hi NAME=Joe \"echo $GREETING && echo $NAME\""
|
140 | }
|
141 | }
|
142 | ```
|
143 |
|
144 | The rule of thumb is: if you want to pass to `cross-env` a command that contains
|
145 | special shell characters _that you want interpreted_, then use
|
146 | `cross-env-shell`. Otherwise stick to `cross-env`.
|
147 |
|
148 | On Windows you need to use `cross-env-shell`, if you want to handle
|
149 | [signal events](https://nodejs.org/api/process.html#process_signal_events)
|
150 | inside of your program. A common case for that is when you want to capture a
|
151 | `SIGINT` event invoked by pressing `Ctrl + C` on the command-line interface.
|
152 |
|
153 | ## Windows Issues
|
154 |
|
155 | Please note that `npm` uses `cmd` by default and that doesn't support command
|
156 | substitution, so if you want to leverage that, then you need to update your
|
157 | `.npmrc` to set the `script-shell` to powershell.
|
158 | [Learn more here](https://github.com/kentcdodds/cross-env/issues/192#issuecomment-513341729).
|
159 |
|
160 | ## Inspiration
|
161 |
|
162 | I originally created this to solve a problem I was having with my npm scripts in
|
163 | [angular-formly][angular-formly]. This made contributing to the project much
|
164 | easier for Windows users.
|
165 |
|
166 | ## Other Solutions
|
167 |
|
168 | - [`env-cmd`](https://github.com/toddbluhm/env-cmd) - Reads environment
|
169 | variables from a file instead
|
170 | - [`@naholyr/cross-env`](https://www.npmjs.com/package/@naholyr/cross-env) -
|
171 | `cross-env` with support for setting default values
|
172 |
|
173 | ## Contributors
|
174 |
|
175 | Thanks goes to these people ([emoji key][emojis]):
|
176 |
|
177 |
|
178 |
|
179 |
|
180 | <table>
|
181 | <tr>
|
182 | <td align="center"><a href="https://kentcdodds.com"><img src="https://avatars.githubusercontent.com/u/1500684?v=3" width="100px;" alt=""/><br /><sub><b>Kent C. Dodds</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/commits?author=kentcdodds" title="Code">π»</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=kentcdodds" title="Documentation">π</a> <a href="#infra-kentcdodds" title="Infrastructure (Hosting, Build-Tools, etc)">π</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=kentcdodds" title="Tests">β οΈ</a></td>
|
183 | <td align="center"><a href="https://zhuangya.me"><img src="https://avatars1.githubusercontent.com/u/499038?v=3" width="100px;" alt=""/><br /><sub><b>Ya Zhuang </b></sub></a><br /><a href="#plugin-zhuangya" title="Plugin/utility libraries">π</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=zhuangya" title="Documentation">π</a></td>
|
184 | <td align="center"><a href="https://wopian.me"><img src="https://avatars3.githubusercontent.com/u/3440094?v=3" width="100px;" alt=""/><br /><sub><b>James Harris</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/commits?author=wopian" title="Documentation">π</a></td>
|
185 | <td align="center"><a href="https://github.com/compumike08"><img src="https://avatars1.githubusercontent.com/u/8941730?v=3" width="100px;" alt=""/><br /><sub><b>compumike08</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/issues?q=author%3Acompumike08" title="Bug reports">π</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=compumike08" title="Documentation">π</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=compumike08" title="Tests">β οΈ</a></td>
|
186 | <td align="center"><a href="https://github.com/danielo515"><img src="https://avatars1.githubusercontent.com/u/2270425?v=3" width="100px;" alt=""/><br /><sub><b>Daniel RodrΓguez Rivero</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/issues?q=author%3Adanielo515" title="Bug reports">π</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=danielo515" title="Code">π»</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=danielo515" title="Documentation">π</a></td>
|
187 | <td align="center"><a href="https://github.com/inyono"><img src="https://avatars2.githubusercontent.com/u/1508477?v=3" width="100px;" alt=""/><br /><sub><b>Jonas Keinholz</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/issues?q=author%3Ainyono" title="Bug reports">π</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=inyono" title="Code">π»</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=inyono" title="Tests">β οΈ</a></td>
|
188 | <td align="center"><a href="https://github.com/hgwood"><img src="https://avatars3.githubusercontent.com/u/1656170?v=3" width="100px;" alt=""/><br /><sub><b>Hugo Wood</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/issues?q=author%3Ahgwood" title="Bug reports">π</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=hgwood" title="Code">π»</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=hgwood" title="Tests">β οΈ</a></td>
|
189 | </tr>
|
190 | <tr>
|
191 | <td align="center"><a href="https://github.com/thomasthiebaud"><img src="https://avatars0.githubusercontent.com/u/3715715?v=3" width="100px;" alt=""/><br /><sub><b>Thiebaud Thomas</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/issues?q=author%3Athomasthiebaud" title="Bug reports">π</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=thomasthiebaud" title="Code">π»</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=thomasthiebaud" title="Tests">β οΈ</a></td>
|
192 | <td align="center"><a href="https://daniel.blog"><img src="https://avatars1.githubusercontent.com/u/1715800?v=3" width="100px;" alt=""/><br /><sub><b>Daniel Rey LΓ³pez</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/commits?author=DanReyLop" title="Code">π»</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=DanReyLop" title="Tests">β οΈ</a></td>
|
193 | <td align="center"><a href="http://amilajack.com"><img src="https://avatars2.githubusercontent.com/u/6374832?v=3" width="100px;" alt=""/><br /><sub><b>Amila Welihinda</b></sub></a><br /><a href="#infra-amilajack" title="Infrastructure (Hosting, Build-Tools, etc)">π</a></td>
|
194 | <td align="center"><a href="https://twitter.com/paulcbetts"><img src="https://avatars1.githubusercontent.com/u/1396?v=3" width="100px;" alt=""/><br /><sub><b>Paul Betts</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/issues?q=author%3Apaulcbetts" title="Bug reports">π</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=paulcbetts" title="Code">π»</a></td>
|
195 | <td align="center"><a href="https://github.com/turnerhayes"><img src="https://avatars1.githubusercontent.com/u/6371670?v=3" width="100px;" alt=""/><br /><sub><b>Turner Hayes</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/issues?q=author%3Aturnerhayes" title="Bug reports">π</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=turnerhayes" title="Code">π»</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=turnerhayes" title="Tests">β οΈ</a></td>
|
196 | <td align="center"><a href="https://github.com/sudo-suhas"><img src="https://avatars2.githubusercontent.com/u/22251956?v=4" width="100px;" alt=""/><br /><sub><b>Suhas Karanth</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/commits?author=sudo-suhas" title="Code">π»</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=sudo-suhas" title="Tests">β οΈ</a></td>
|
197 | <td align="center"><a href="https://github.com/sventschui"><img src="https://avatars3.githubusercontent.com/u/512692?v=4" width="100px;" alt=""/><br /><sub><b>Sven</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/commits?author=sventschui" title="Code">π»</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=sventschui" title="Documentation">π</a> <a href="#example-sventschui" title="Examples">π‘</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=sventschui" title="Tests">β οΈ</a></td>
|
198 | </tr>
|
199 | <tr>
|
200 | <td align="center"><a href="https://github.com/NicoZelaya"><img src="https://avatars0.githubusercontent.com/u/5522668?v=4" width="100px;" alt=""/><br /><sub><b>D. NicolΓ‘s Lopez Zelaya</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/commits?author=NicoZelaya" title="Code">π»</a></td>
|
201 | <td align="center"><a href="http://bithavoc.io"><img src="https://avatars3.githubusercontent.com/u/219289?v=4" width="100px;" alt=""/><br /><sub><b>Johan Hernandez</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/commits?author=bithavoc" title="Code">π»</a></td>
|
202 | <td align="center"><a href="https://github.com/jnielson94"><img src="https://avatars3.githubusercontent.com/u/13559161?v=4" width="100px;" alt=""/><br /><sub><b>Jordan Nielson</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/issues?q=author%3Ajnielson94" title="Bug reports">π</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=jnielson94" title="Code">π»</a> <a href="https://github.com/kentcdodds/cross-env/commits?author=jnielson94" title="Tests">β οΈ</a></td>
|
203 | <td align="center"><a href="https://nz.linkedin.com/in/jsonc11"><img src="https://avatars0.githubusercontent.com/u/5185660?v=4" width="100px;" alt=""/><br /><sub><b>Jason Cooke</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/commits?author=Jason-Cooke" title="Documentation">π</a></td>
|
204 | <td align="center"><a href="https://github.com/bibo5088"><img src="https://avatars0.githubusercontent.com/u/17709887?v=4" width="100px;" alt=""/><br /><sub><b>bibo5088</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/commits?author=bibo5088" title="Code">π»</a></td>
|
205 | <td align="center"><a href="https://codefund.io"><img src="https://avatars2.githubusercontent.com/u/12481?v=4" width="100px;" alt=""/><br /><sub><b>Eric Berry</b></sub></a><br /><a href="#fundingFinding-coderberry" title="Funding Finding">π</a></td>
|
206 | <td align="center"><a href="https://michaeldeboey.be"><img src="https://avatars3.githubusercontent.com/u/6643991?v=4" width="100px;" alt=""/><br /><sub><b>MichaΓ«l De Boey</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/commits?author=MichaelDeBoey" title="Code">π»</a></td>
|
207 | </tr>
|
208 | <tr>
|
209 | <td align="center"><a href="https://github.com/lauriii"><img src="https://avatars0.githubusercontent.com/u/1845495?v=4" width="100px;" alt=""/><br /><sub><b>Lauri Eskola</b></sub></a><br /><a href="https://github.com/kentcdodds/cross-env/commits?author=lauriii" title="Documentation">π</a></td>
|
210 | </tr>
|
211 | </table>
|
212 |
|
213 |
|
214 |
|
215 |
|
216 |
|
217 | This project follows the [all-contributors][all-contributors] specification.
|
218 | Contributions of any kind welcome!
|
219 |
|
220 | > Note: this was added late into the project. If you've contributed to this
|
221 | > project in any way, please make a pull request to add yourself to the list by
|
222 | > following the instructions in the `CONTRIBUTING.md`
|
223 |
|
224 | ## LICENSE
|
225 |
|
226 | MIT
|
227 |
|
228 | [npm]: https://www.npmjs.com/
|
229 | [node]: https://nodejs.org
|
230 | [build-badge]:
|
231 | https://img.shields.io/travis/kentcdodds/cross-env.svg?style=flat-square
|
232 | [build]: https://travis-ci.org/kentcdodds/cross-env
|
233 | [win-build-badge]:
|
234 | https://img.shields.io/appveyor/ci/kentcdodds/cross-env.svg?style=flat-square
|
235 | [win-build]: https://ci.appveyor.com/project/kentcdodds/cross-env
|
236 | [coverage-badge]:
|
237 | https://img.shields.io/codecov/c/github/kentcdodds/cross-env.svg?style=flat-square
|
238 | [coverage]: https://codecov.io/github/kentcdodds/cross-env
|
239 | [version-badge]: https://img.shields.io/npm/v/cross-env.svg?style=flat-square
|
240 | [package]: https://www.npmjs.com/package/cross-env
|
241 | [downloads-badge]: https://img.shields.io/npm/dm/cross-env.svg?style=flat-square
|
242 | [npmtrends]: https://www.npmtrends.com/cross-env
|
243 | [license-badge]: https://img.shields.io/npm/l/cross-env.svg?style=flat-square
|
244 | [license]: https://github.com/kentcdodds/cross-env/blob/master/other/LICENSE
|
245 | [prs-badge]:
|
246 | https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
|
247 | [prs]: http://makeapullrequest.com
|
248 | [coc-badge]:
|
249 | https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
|
250 | [coc]:
|
251 | https://github.com/kentcdodds/cross-env/blob/master/other/CODE_OF_CONDUCT.md
|
252 | [emojis]: https://github.com/kentcdodds/all-contributors#emoji-key
|
253 | [all-contributors]: https://github.com/kentcdodds/all-contributors
|
254 | [win-bash]: https://msdn.microsoft.com/en-us/commandline/wsl/about
|
255 | [angular-formly]: https://github.com/formly-js/angular-formly
|
256 | [cross-spawn]: https://www.npmjs.com/package/cross-spawn
|
257 | [ts-loader]: https://www.npmjs.com/package/ts-loader
|
258 | [malware]:
|
259 | http://blog.npmjs.org/post/163723642530/crossenv-malware-on-the-npm-registry
|