Home

Awesome

nodist

Join the chat at https://gitter.im/marcelklehr/nodist

A node.js and npm version manager for the windows folks out there. Inspired by n. And nodenv.

Heads up! Nodist v0.10 is here! Nodist supports cmd, Powershell, Git bash and Cygwin!

C:\> nodist + 5
5.11.0

C:\> nodist global 5
5

C:\> node -v
v5.11.0

C:\> nodist
  0.10.26
  4.4.3
> 5.11.0 (global: 5)

(see Usage)

Known issues

Please read this!

Over the past months several problems have presented themselves, which are due to the way nodist works and are hard to fix:

Installation

Nodist was designed to replace any existing node.js installation, so if node is already installed on your machine, uninstall it first.

with the installer

  1. Download the installer from the releases page
  2. Run the installer and follow the install wizard

via chocolatey

For this you'll need chocolatey, of course.

  1. choco install nodist

Activating nodist in git bash

Git bash integration is setup automatically.

Activating nodist in cygwin

Before you are able to use nodist in cygwin you need to run the following in your cygwin terminal after installing nodist:

cat "$NODIST_PREFIX/bin/nodist_bash_profile_content.sh" >> ~/.bashrc
source ~/.bashrc

Activating nodist in PowerShell

You might need to 'Unblock' the file bin\nodist.ps1 by right-clicking on it in the Explorer and selecting that menu entry.

If you cannot see the unblock option after right-clicking > Properties in Explorer you can also perform the unblock via the following PowerShell command:

unblock-file -path "C:\Program Files (x86)\Nodist\bin\nodist.ps1"

If you still cannot run nodist you may also need amend your ExecutionPolicy setting.

Warning: Please ensure you understand the risks associated with the different execution policies by first reviewing about_Execution_Policies - Microsoft Docs

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

Make it work in your IDE

If your IDE cannot access node or npm right away, don't fret! Find the relevant configuration settings and either set path\to\Nodist\bin as the Node installation dir or set path\to\Nodist\bin\node.exe as the path to the node binary directly.

Similar for npm: either set ...\Nodist\bin as the installation path or ...\Nodist\bin\npm.cmd directly. Some IDEs (eg. WebStorm) require you to set the path to an npm package containing bin\npm-cli.js. Nodist comes with a proxy npm folder: Simply set ...\Nodist\npm as the npm package (this feature is experimental and feedback is appreciated!).

Migrating from 0.7 or lower

If you're looking to upgrade your Nodist installation, the easiest way is to uninstall (see below) the old installation and install the new version with the installer above. You may need to reset your per-directory node version settings in order for them to work in v0.8 (ones set using nodist v0.6 should work fine, ones set using v0.7 will not).

Important usage changes in v0.8

Starting in v0.8 Nodist employs lazy version pattern evaluation. This means that setting versions per env/locally/globally doesn't set an explicit version, if you didn't give one. Instead the node.exe shim chooses a suitable version at runtime. Commands for installing a version and setting a requirement have been separated, thus, to update your node version (if your global version is set to 6, e.g.), you now need to run nodist + 6 (i.e. nodist 6 doesn't do that for you anymore), which is probably how it should have worked all along.

Uninstall (v0.7)

  1. Run the uninstaller either from the directory where you installed nodist, or from the Software Control Panel

  2. Make sure to completely remove the nodist directory. (This will remove all your globally installed npm modules. If you don't want that, remove everything else, other than nodist\bin\.)

Uninstall (before v0.7)

  1. Remove <..path..>\nodist\bin from your path. (how?).

  2. Remove the NODIST_PREFIX env var.

  3. Delete the nodist directory

  4. Run npm config delete prefix on the command prompt to restore NPM functionality if you are going back to the official node install.

Usage

Nodist allows you to set version requirements for different scopes. Version requirements can be fully specified versions, like 4.0.0 or patterns like 0.12, 4.x, ~5 or latest. io.js is supported natively: Since node and io.js versions form a continuum you can simply use io.js versions as if they were node versions. Setting a requirement installs a matching version only if there is no other matching version already installed; otherwise existing installed versions will get referenced when executing node.exe.

Scope precedence

The following is a list of all scopes ordered by precedence (the first scope is the one with the highest priority; only if it's not set, the second scope is examined).

  1. Environment (NODIST_NODE_VERSIONand NODIST_NPM_VERSION env vars)
  2. (optional:) Package (package.json with an engines field in the directory of interest or one of its parent directories)
  3. Directory (.node-version or .npm-version in the directory of interest or one of its parent directories)
  4. Global (globally set node or npm version)

When you're just running node, the directory of interest is the directory of the javascript file to be executed. When running npm, it is the current working directory.

Package.json inspection is turned off by default as of nodist v0.8.5. You can turn it on by setting NODIST_INSPECT_PACKAGEJSON=1.

npm / npx

Any instances of node invoked by npm/npx will be locked to the same version npm/npx runs on.

Currently, all node and npm versions share the same global npm module space.

If you have installed native modules (globally or locally) you may have to run npm rebuild after changing the node version (implicitly or explicitly). There is an open issue about how to avoid rebuilding globally installed native modules, feedback/input is welcome.

The npx shim will try to run the npx shipped with the currently selected npm version.

Commands

All commands automatically install the latest matching version before setting the version pattern.

> nodist
# Lists installed versions highlighting the active ones.

> nodist global 4.x
# Sets the global node version requirement

> nodist local 4.x
# Sets the node version requirement per directory (including all subdirectories).

> nodist env 4.x
# Sets the node version requirement per terminal.

> nodist npm global 3.x
# Set global npm version requirement.

> nodist npm global match
# Tell nodist to always choose the npm version that matches the current node version.
# (the current node version may be determined by env, local or global requirements)

> nodist npm local 2.x
# Set the npm version requirement for the current directory.

> nodist npm env 2.x
# Set the npm version requirement for the current terminal environment.

call nodist env 4.x
# In a batch script use `call`.

> nodist dist
# Lists all available node versions.

> nodist + 4.x
# Just checks, if the version is installed and installs it if not.

> nodist + all
# will install *everything*.

> nodist - 4.1.1
# Removes a version.

> nodist --help
# Displays a complete list of commands with examples.

Settings

> set HTTP_PROXY=http://myproxy.com:8213
# Set a proxy to use for fetching the executables
# (you may also use `HTTP_PROXY`/`http_proxy`/`HTTPS_PROXY`/`https_proxy`).

> set NODIST_NODE_MIRROR=https://mymirror.com/dist
# Set a mirror that has the same directory structure as https://nodejs.org/dist
# (you may also use `NODIST_IOJS_MIRROR` in the same fashion).

> set NODIST_X64=0
# (Set to `1` to enforce 64bit, `0` to enforce 32bit.)

> set NODIST_INSPECT_PACKAGEJSON=1
# Enable package.json inspection: Nodist will check the engines field of the package.json file of scripts to be executed and use the node version specified there. Turned off by default as of v0.8.5.

> set NODIST_GITHUB_TOKEN=your_github_personal_access_token
# By default Nodist makes request to the GitHub API to list npm releases without any authentication, which is subject to [rate limiting](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting). By using your own [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) Nodist will be able to make more requests per hour.
# Note: for security purposes it's best to use a token just for Nodist. The `repo:public_repo` scope should be more than sufficient.

Details

Node executables are stored in NODIST_PREFIX\v and NODIST_PREFIX\v-x64, npm versions in NODIST_PREFIX\npmv. The global node.exe` is a shim and chooses the right node version to run based on the various version settings. The same applies for npm.

As the global node version will be subject to change, nodist comes with its own dedicated node binary.

Got ideas? Doesn't work for you? Want to give feedback?

File an issue and tell me what you'd change or add or what doesn't work for you. Every issue is welcome!

Malware warnings

Nodist is not a virus. Nonetheless, some malware detection tools report the Nodist installer as a virus. If this happens, please contact the vendor of your malware detection tool and report the Nodist installer as a false positive.

Debugging

To see all debug messages, set the DEBUG env var before running nodist or node as follows:

> set DEBUG=nodist:*

Testing

The default test suite can be run using npm

$ npm test

Testing also accepts env variables for using a mirror to download from, as well as setting a proxy.

> set NODIST_NODE_MIRROR=http://nodejs.serverpals.com/dist
> vows --spec test\cli-test.js

Building

Building nodist requires

If you have met all requirements, run the build command:

> npm run build

Afterwards you'll find the installer in build/out/NodistSetup-vX.X.X.exe and fully prepared installation folder in build/out/staging (you could zip this, for example). The chocolatey package will be in build/out/package, you can run cpack and cpush --source https://chocolatey.org/ inside that directory (if you are a registered maintainer).

Legal

Copyright (c) 2012-2023 by Marcel Klehr, Bryan Tong (@nullivex)
MIT License

Changelog

v0.10.3

v0.10.2

v0.9.1

v0.9.0

v0.8.8

v0.8.7

v0.8.6

v0.8.5

v0.8.4

v0.8.3

v0.8.2

v0.8.1

v0.8.0

v0.7.2

v0.7.1

v0.7.0 (thanks to @nullivex)

v0.6.1

v0.6.0

v0.5.2

v0.5.1

v0.5.0

v0.4.8

v0.4.7

v0.4.6

v0.4.5

v0.4.4

v0.4.3

v0.4.2

v0.4.1

v0.4.0

v0.3.11

v0.3.10

v0.3.9

v0.3.8

v0.3.7

v0.3.5

v0.3.4

v0.3.3

v0.3.2

v0.3.1

v0.3.0

v0.2.8

v0.2.7

v0.2.6

v0.2.5

v0.2.4

v0.2.3