0112288e01
NOTE: For the vast majority of users running supported versions of Node.js, this should not require any changes and you can update without issue. BREAKING CHANGE: This is a major rewrite that changes the module format from CommonJS to ESM-only. The package now requires Node.js >=20 and only exports ESM modules (not relevant in most cases). BREAKING CHANGE: The package.json exports have been updated to remove CommonJS support. Only ESM imports are now supported. BREAKING CHANGE: All source files have been converted from JavaScript to TypeScript, requiring TypeScript-aware tooling for development. - Replace Jest with Vitest for testing - Convert all source files from .js to .ts with proper TypeScript types - Use zshy for ESM-only builds (removes CJS support) - Adopt @epic-web/config for TypeScript, ESLint, and Prettier - Update to Node.js >=20 requirement - Remove kcd-scripts dependency - Add comprehensive e2e tests with GitHub Actions matrix testing - Update GitHub workflow with caching and cross-platform testing - Modernize documentation and remove outdated sections - Update all dependencies to latest versions - Add proper TypeScript declarations and exports The tool maintains its original functionality while being completely modernized with the latest tooling and best practices Co-authored-by: GitHub Action <[email protected]>
3.0 KiB
Executable File
cross-env 🔀
Run scripts that set and use environment variables across platforms.
The Problem
Most Windows command prompts will choke when you set environment variables with
NODE_ENV=production like that. 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%.
The 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
npm install --save-dev cross-env
Usage
I use this in my npm scripts:
{
"scripts": {
"build": "cross-env NODE_ENV=production node ./start.js"
}
}
Ultimately, the command that is executed (using cross-spawn)
is:
node ./start.js
The NODE_ENV environment variable will be set by cross-env.
Multiple Environment Variables
You can set multiple environment variables at a time:
{
"scripts": {
"build": "cross-env FIRST_ENV=one SECOND_ENV=two node ./my-program"
}
}
Complex Commands
You can also split a command into several ones, or separate the environment variables declaration from the actual command execution:
{
"scripts": {
"parentScript": "cross-env GREET=\"Joe\" npm run childScript",
"childScript": "cross-env-shell \"echo Hello $GREET\""
}
}
JSON Strings
For JSON strings (e.g., when using ts-loader):
{
"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 (').
cross-env vs cross-env-shell
The cross-env module exposes two bins: cross-env and cross-env-shell.
cross-env: Executes commands usingcross-spawncross-env-shell: Uses theshelloption from Node'sspawn
Use cross-env-shell when you need an environment variable to be set across an
entire inline shell script, rather than just one command:
{
"scripts": {
"greet": "cross-env-shell GREETING=Hi NAME=Joe \"echo $GREETING && echo $NAME\""
}
}
Rule of thumb: 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.
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.
Requirements
- Node.js >= 20
License
MIT