InstallNodeJs Task

Overview

The InstallNodeJs task installs a local, private copy of Node.js.

By default, it is installed into a .node directory in the build root, i.e. the node commands are in the .node directory. Use the Path property to install it to a different location. The directory where Node.js is installed is added to the beginning of the PATH environment variable so that future commands use that version of Node.js and any installed Node.js tools/modules.

By default, the task installs the version of Node.js given by, in order of precedence:

• the Version property task.
• the contents of the .node-version file (in the build root).
• the value of the whiskey.node property in the package.json file.

If version information is missing, the task installs the latest LTS version of Node.js.

The version to install can be a one- or two-part partial version number. If using a one- or two-part version number, the task will install the latest version for any missing parts. For example, if using 22 as the version, the task would install Node.js v22.8.0 (which is the latest v22 version at the time of this writing). If using 20.4, Node.js v20.4.1 would be installed.

If the correct version of Node.js is already installed, the task does not reinstall Node.js. If the incorrect version of Node.js is installed, the installation directory is deleted and the correct version is installed.

The task also supports pinning NPM's version. Use the NpmVersion task property or add a whiskey.npm property to package.json. Partial version numbers are supported. If no NPM version is given, whatever version that ships with Node.js would be used.

Properties

• Version: the version of Node.js to installed. Partial version numbers supported. The highest, latest version number is used for any missing part of the version number. If this is omitted, the task will read the version from a .node-version in the build root, if it exists. If there is no .node-version file, the task reads the version from a whiskey.node property in the package.json. If no version is given, the latest LTS version is installed.
• NpmVersion: the version of NPM to use. Partial version numbers are supported. The highest, latest version number is used for any missing part of the version number. The task runs npm@NPMVERSION install -g to install NPM. If this property is omitted, the task reads the version from a whiskey.npm property in the package.json file. If no NPM version number given, then NPM is left at the version that ships with Node.js.
• PackageJsonPath: if you want the task to read the version of Node.js and/or NPM to install from your package.json file, set this property to the path to that package.json file, relative to the whiskey.yml file. By default, the task uses a package.json file in the build root, if one exists.
• Path: the directory where Node.js should be installed. By default, installs to a .node directory in the build root. Should be a path relative to the whiskey.yml file. The directory is created if it doesn't exist. Installing outside the build root is not allowed.
• Cpu: by default, the task attempts to download the Node.js package that matches the pattern node-VERSION-PLATFORM-CPU.extension where the platform is win for Windows, linux for Linux, or darwin for macOS and the CPU is x64 for 64-bit operating systems and x86 otherwise. Use this property to set what the CPU part of the package name is.

Examples

Example 1

Build:
- InstallNodeJs

Demonstrates the simplest way to use this task. If there is no .node-version file nor a whiskey.node property in the package.json file, this would install the latest LTS version of Node.js.

Example 2

Build:
- InstallNodeJs:
    Version: 22
    NpmVersion: 10

Demonstrates how to pin Node.js and NPM to specific versions by using the Version and NpmVersion properties. In this example, at the time of writing, would install Node.js 22.8.0 and NPM 10.8.3 into a .node directory in the build root.

Example 3

Given there is a .node-version file with contents:

20

this example:

Build:
- InstallNodeJs

demonstrates how to install Node.js using a version saved in that .node-version file. This example would install Node.js 20.17.0 (at the time of writing) into a .node directory in the build root.

Example 4

Given there is a section in the package.json file that looks like this:

    "whiskey": {
        "node": "20",
        "npm": "10"
    }

this example:

Build:
- InstallNodeJs

would install Node.js 20.17.0 and NPM 10.8.4 into a .node directory in the build root.

Example 5

Build:
- InstallNodeJs:
    Path: app\.node

This example demonstrates how to install Node.js into a custom directory, in this case, the app\.node directory.

Example 6

- InstallNodeJs:
    Cpu: arm64

Demonstrates how to install Node.js on Apple silicon by using the Cpu property to control the CPU portion of the package file name to download.