@axetroy/virtual-node-env NPM

Latest Version Repo Size

Background

When developing NodeJS projects, we often need to switch NodeJS versions. For example, project A requires 16.x.y, while project B uses 20.x.y.

However, global version management tools like nvm cannot meet the requirements. It has the following problems:

nvm is not cross-platform, and it is not very convenient to use on Windows.
nvm needs to install the specified version in advance to switch, which is not very friendly to the CI/CD environment.
In a Monorepo, there may be a situation where package A requires 16.x.y, while package B requires 20.x.y. In this case, nvm cannot solve this problem well.

So I developed this tool to solve this problem.

It will run the command with the appropriate NodeJS version according to the NodeJS version constraint in packages.json.

Usage

# Automatically select the NodeJS version to run the command
$ virtual-node-env node -v

# Specify the NodeJS version and run the specified command
$ virtual-node-env use ^18 node -v

Integrate into your NodeJS project

Add NodeJS version constraint in package.json.

+  "engines": {
+    "node": "^20.x.x"
+  },
  "scripts": {
    "dev": "vite dev"
  }

Run the script with virtual-node-env command.

- yarn dev
+ virtual-node-env yarn dev

Run with --help to see more options.

$ virtual-node-env --help
virtual-node-env - A virtual node environment for node.js, node version manager for projects.

USAGE:
  virtual-node-env [OPTIONS] <ARGS...>
  virtual-node-env [OPTIONS] run <ARGS...>
  virtual-node-env [OPTIONS] use <CONSTRAINT> <ARGS...>
  virtual-node-env [OPTIONS] rm <CONSTRAINT> <ARGS...>
  virtual-node-env [OPTIONS] clean
  virtual-node-env [OPTIONS] ls
  virtual-node-env [OPTIONS] ls-remote

COMMANDS:
  run <ARGS...>               Automatically select node version to run commands
  use <CONSTRAINT> <ARGS...>  Use the specified version of node to run the command
  rm|remove <CONSTRAINT>      Remove the specified version of node that installed by virtual-node-env
  clean                       Remove all the node version that installed by virtual-node-env
  ls|list                     List all the installed node version
  ls-remote|list-remote       List all the available node version
  <ARGS...>                   Alias for 'run <ARGS...>' but shorter

OPTIONS:
  --help|-h                   Print help information
  --version|-v                Print version information

ENVIRONMENT VARIABLES:
  NODE_MIRROR                 The mirror of the nodejs download, defaults to: https://nodejs.org/dist/
                              Chinese users defaults to: https://registry.npmmirror.com/-/binary/node/
  NODE_ENV_DIR                The directory where the nodejs is stored, defaults to: $HOME/.virtual-node-env
  DEBUG                       Print debug information when set DEBUG=1

EXAMPLES:
  virtual-node-env node -v
  virtual-node-env run node -v
  virtual-node-env use v14.17.0 node -v

SOURCE CODE:
  https://github.com/axetroy/virtual-node-env

Installation

Install via Cask (Mac/Linux/Windows)

$ cask install github.com/axetroy/virtual-node-env
$ virtual-node-env --help

Install via npm

$ npm install @axetroy/virtual-node-env -g
$ virtual-node-env --help
# or use the alias
$ vnode --help

Uninstall

$ virtual-node-env clean
# then remove the binary file or uninstall via package manager

NodeJS version selection algorithm

This section explains what happens when you run virtual-node-env and how it selects the node version.

Check for the presence of package.json.
If package.json exists:
1. If the engines.node field is specified, use the indicated version.
  1. If the currently installed version matches engines.node, the command is run using the currently installed version.
  2. Otherwise, select the latest matching version from the remote list, install it, and run the command.
2. Otherwise, run the command directly.
Otherwise, run the command directly.