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

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