X-var NPM | npm.io

x-var

cross-var and cross-env revamped! Same syntax under Linux and Windows. .env supported!

Capabilities

Use the same syntax for all operating systems Use the same syntax for all operating systems
Load .env files, see env files
Set environment variables in the command line for all operating systems (both x-var and x-env)
Postpone the variable replacement

Use the same syntax for all operating systems

The variable placeholders are replaced by the x-var package. The placeholders are in the form $VAR or %VAR%. See the section Caveats of the Linux and Windows command line compatibility for more details.

Look at the examples below. If you're Linux addicted:

{
  "scripts": {
    "version": "x-var echo \\$npm_package_version"
  }
}

or, if you lean towards the Windows style:

{
  "scripts": {
    "version": "x-var echo %npm_package_version%"
  }
}

Both will render the version of the package.

Source of variables

There is a bunch of sources of variables:

local host operating system variables
CI/CI
docker
user variables
npm config - npm configuration
package.json - package.json file
...

All these variables are available in the npm scripts. Execute npm run env to see the list of available variables.

env files

Some projects use .env files, i.e.

.env - default variables
.env-stage - staging variables
.env-prod - production variables

For such cases there is an x-env utility:

{
  "scripts": {
    "run:dev": "x-env echo \\$DEPLOY_HOST",
    "run:prod": "x-env -e=.prod.env echo \\$DEPLOY_HOST"
  }
}

Note:

The x-env utility just loads the .env file and executes the command.
The -e option is used to specify the custom .env file.
dotenv package is used under the hood. So, almost all capabilities of these packages are kept.

Warning - the .env is loaded directly into process.env which makes all variables to be visible to the target application or script. If the .env is used by the target application, consider to use x-var to avoid conflicts.

Generally speaking, the x-env utility should be used for the most of the cases. The x-var should be used to avoid using .env files.

Caveats of the Linux and Windows command line compatibility

The Linux command line uses $ to access the environment variables, while the Windows command line uses %. However, this is not the only difference. The Linux command line replaces the variables before the command is executed, while the Windows command line replaces the variables during the command execution. Consider a simple example:

TEST=PASSED echo $TEST

The expected output is PASSED. But the actual output is empty! This is because the $TEST is replaced by the shell before the command is executed. The very same if we run the command in the npm scripts:

{
  "scripts": {
    "example": "TEST=PASSED echo $TEST"
  }
}

The output is empty as well. To fix this you might need to escape the dollar $ sign:

{
  "scripts": {
    "example": "TEST=PASSED echo \\$TEST"
  }
}

However, this won't work being run under Windows! The solution - Use the same syntax for all operating systems

Linux only solution

Despite the fact that Linux command line replaces the variables before the command is executed, there are still some useful features. If the cross-platform compatibility is not required, the encapsulation of the variable in the single quotes will work: Late evaluation of the variable:

x-var TEST=PASSED echo \$TEST

same as

TEST=PASSED x-var echo \$TEST

In this case the variable is not replaced by the shell, but by the x-var package.

Similar packages

cross-var - the original package
cross-env - the most popular package
dotenv - the package to load .env files

Difference with the cross-env package

The cross-env package is barely maintained
The cross-env package is unable to load .env files. x-var uses dotenv under the hood.
This does not work in cross-env and it works in x-var:
```
cross-env TEST=value echo \$TEST
```
And this
```
cross-env TEST=value echo %TEST%
```
Cross-env relies on unmaintained cross-spawn package. The x-var uses shell.js package.