repository·main·Indexed 27 days ago
https://github.com/kentcdodds/cross-envA utility to set and use environment variables in scripts across Windows, macOS, and Linux using a consistent POSIX-like syntax. It provides the `cross-env` binary for single commands and `cross-env-shell` for inline shell scripts and complex commands. The package also includes a `crossEnv()` function for programmatic execution with cross-platform compatibility and signal handling.
Install cross-env as a development dependency in your project.
Note on Node.js versions:
npm install --save-dev cross-env@7.npm install --save-dev cross-envThe cross-env-shell binary is used when you need to execute an entire inline shell script or when you want environment variables to apply to multiple commands in a series.
Rule of thumb: Use cross-env-shell if your command contains special shell characters (like && or $VAR) that you want the shell to interpret. Otherwise, use cross-env.
On Windows, use cross-env-shell if you need to handle signal events (like SIGINT via Ctrl + C) inside your program.
{
"scripts": {
"greet": "cross-env-shell GREETING=Hi NAME=Joe \"echo $GREETING && echo $NAME\""
}
}cross-env in your package.json scripts to set environment variables in a POSIX-like syntax that works across Windows and other platforms. You can set a single variable or multiple variables at once.npm uses cmd on Windows, which does not support command substitution. If you want to leverage command substitution in your scripts, you must update your .npmrc to set the script-shell to powershell.ts-loader), you must use a triple backslash (\\]) before the double quotes (") and ensure there are **no single quotes** ('`) used. This ensures compatibility across Windows and UNIX.The package provides two distinct binaries with different execution behaviors:
cross-env: Executes commands using cross-spawn. Best for single commands where you just need to set environment variables.cross-env-shell: Uses the shell option from Node's spawn. Best for inline shell scripts, multiple commands in series, or when using shell-specific syntax like $VARIABLE or signal handling.The crossEnv() function allows you to run a command with specific environment variables set, ensuring cross-platform compatibility (especially for Windows). It parses an array of strings where the initial elements are KEY=VALUE pairs, followed by the command and its arguments.
When the command executes, crossEnv() handles process signals (like SIGINT or SIGTERM) and maps the exit code. If a process is terminated by SIGINT, crossEnv() treats the exit code as 0 to reflect a user-initiated exit.
The cross-env command allows you to set environment variables in a way that works across different platforms (Windows, macOS, and Linux). You can invoke it directly from your terminal or via npx. It accepts the environment variable assignments followed by the command you wish to execute.
Example usage:
npx cross-env NODE_ENV=production node server.jscross-env-shell CLI command allows you to run commands within a cross-environment shell. It is a specialized entrypoint that executes the provided arguments through a shell, which is useful when your command relies on shell-specific features or syntax that standard cross-env might not handle directly.The crossEnv() function accepts an optional options object of type CrossEnvOptions to control how the command is spawned.
| Option | Type | Description |
|---|---|---|
shell | boolean | If true, the command is executed within a shell. |
Note: crossEnv() automatically sets stdio: 'inherit' so that the spawned process shares the parent's terminal input/output.
The crossEnv() function returns a ProcessResult object (or null if no command is provided). This object describes the outcome of the spawned process.
| Property | Type | Description |
|---|---|---|
exitCode | number | null | The exit code of the process. Returns null if the OS killed the process (e.g., out of memory). |
signal | string | null | The signal that caused the process to terminate (e.g., 'SIGINT'). |
If exitCode is null and the signal is 'SIGINT', cross-env internally treats the exit code as 0 when exiting the parent process.