# cross-env — Cross-Platform Environment Variables for npm Scripts

> A simple tool for setting environment variables across Windows, macOS, and Linux in npm scripts. Eliminates platform-specific syntax differences with a single consistent command.

## Install

Save as a script file and run:

# cross-env — Cross-Platform Environment Variables for npm Scripts

## Quick Use
```bash
npm install --save-dev cross-env
```
```json
{
  "scripts": {
    "build": "cross-env NODE_ENV=production webpack",
    "test": "cross-env DEBUG=true jest"
  }
}
```

## Introduction
cross-env solves a common pain point in JavaScript projects: setting environment variables in npm scripts behaves differently on Windows versus Unix systems. By prefixing commands with cross-env, developers write one script that works identically across all platforms without worrying about shell syntax differences.

## What cross-env Does
- Sets environment variables in a platform-independent way for npm scripts
- Translates Unix-style `VAR=value command` syntax to work on Windows cmd and PowerShell
- Supports setting multiple environment variables in a single command
- Passes all remaining arguments through to the target command unchanged
- Provides cross-env-shell for commands that need shell-level variable expansion

## Architecture Overview
cross-env parses its arguments to extract key=value pairs, sets them as environment variables in the current process, and then spawns the remaining command as a child process using cross-spawn (a cross-platform replacement for child_process.spawn). The child inherits the modified environment. This approach avoids shell-specific syntax entirely — cross-env handles the translation layer so the npm script author does not need to.

## Self-Hosting & Configuration
- Install as a dev dependency; no global installation needed
- Use directly in package.json scripts with the cross-env prefix
- Set multiple variables by listing them before the command: `cross-env A=1 B=2 command`
- Use cross-env-shell when the command itself needs variable interpolation (e.g., `echo $VAR`)
- Works with any Node.js version from 14 onward

## Key Features
- Single command syntax that works on Windows, macOS, and Linux
- Zero configuration — just prefix your npm script command
- Supports multiple environment variables in one invocation
- cross-env-shell variant for shell-level variable expansion
- Lightweight with minimal dependencies

## Comparison with Similar Tools
- **dotenv / dotenv-cli** — loads variables from .env files; cross-env sets them inline in npm scripts
- **env-cmd** — loads variables from config files with environment-specific overrides; more feature-rich but heavier
- **Shell-specific syntax (export, set)** — works per-platform but breaks cross-platform npm scripts
- **direnv** — loads variables when entering a directory; shell-level tool, not npm-script-focused

## FAQ
**Q: Why not just use export VAR=value?**
A: `export` is a Unix shell command that does not work on Windows cmd or PowerShell. cross-env abstracts this difference.

**Q: When should I use cross-env-shell instead of cross-env?**
A: Use cross-env-shell when your command string itself references environment variables (e.g., `echo $NODE_ENV`). Regular cross-env does not expand variables in the command string.

**Q: Does cross-env persist the variables after the command finishes?**
A: No. Variables are set only for the duration of the child process.

**Q: Is cross-env still needed with modern Node.js?**
A: If your team uses Windows or your CI runs on multiple platforms, yes. Node.js itself does not normalize environment variable syntax in npm scripts.

## Sources
- https://github.com/kentcdodds/cross-env
- https://www.npmjs.com/package/cross-env

---
Source: https://tokrepo.com/en/workflows/asset-ad118c17
Author: Script Depot