Skip to main content

How to install the xPack prerequisites

Overview

All xPack core tools are Node.js CLI application available from the npmjs.com public repository. They can be installed via npm, which runs on top of Node.js.

Install Node.js & npm

The only prerequisite for xPack is a recent version of Node.js (>=18.0.0), as some dependencies require new features. Detailed instructions for each supported platform are provided in the following sections.

$ node --version
v20.18.0

If this is your first time using npm, you'll need to install the Node.js ECMAScript (JavaScript) runtime. The installation process is straightforward and does not clutter system locations. There are two versions of Node.js: LTS (Long Term Service) and Current. Generally, it is safer to use the LTS version, especially on Windows.

The Node Download page

For Windows, the general procedure is to download the package and run the setup as usual (see below for details).

The result is a binary program named node.exe, that can be used to execute JavaScript code from the terminal, and a stub named npm.cmd, executing the npm-cli.js script, which is part of the Node.js module that implements the npm functionality.

node setup

Download the Windows Prebuilt Installer from the Node.js download page (a node-v*-x64.msi file, only x64 is supported) and run the Windows setup as usual, with administrative rights.

tip

If you are not developing native modules, it's best to skip selecting the Tools for Native Modules during installation. This will help you avoid installing Visual Studio and other large packages that you don't need.

The Node.js Tools for Native Modules

The setup process creates a folder, such as C:\Program Files\nodejs, which is automatically added to the system path because it contains the node.exe binary.

C:\>where node.exe
C:\Program Files\nodejs\node.exe
C:\>node --version
v20.18.0

npm update

Node.js comes bundled with a version of npm, which is typically slightly older.

C:\>where npm.cmd
C:\Program Files\nodejs\npm.cmd
C:\>npm --version
10.8.2

It is advisable to update it to the latest version:

C:\>npm install -location=global npm@latest
removed 1 package, and changed 60 packages in 5s

27 packages are looking for funding
run `npm fund` for details

Surprisingly, checking the version often reveals the older version:

C:\>where npm.cmd
C:\Program Files\nodejs\npm.cmd
C:\>npm --version
10.8.2

This happens because, by default, global Node.js packages on Windows are installed in the user home folder, specifically in %APPDATA%\npm (e.g., C:\Users\ilg\AppData\Roaming\npm). This path is not included in the system or user path.

C:\>echo %Path%

It must be manually added before the current path:

C:\>set Path=%APPDATA%\npm;%Path%

To make this setting persistent, execute the following command:

C:\>setx Path "%APPDATA%\npm;%Path%"
info

Please note the syntax differences: setx does not use an equal sign but uses double quotes, which can be problematic if used with set.

info

These commands are valid for the cmd.exe shell. For PowerShell or other shells, please adjust the syntax accordingly.

After this, the new version of the program should be visible:

C:\>npm --version
10.9.0

Git

While not mandatory for using the xPack tools alone, it is recommended to install the Git for Windows package too.

This also installs a bash shell. The xPack Core Tools can run either in either the Windows shells or in the Git bash shell.

PowerShell Execution Policies

Recent Windows versions use PowerShell, which has a more restrictive execution policy designed to prevent the execution of malicious scripts. Unfortunately, this also prevents the execution of Node.js applications.

If you get a message in the console as the one below:

xpm : File C:\Users\...\AppData\Roaming\npm\xpm.ps1 cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at
https:/go.microsoft.com/fwlink/?LinkID=135170.
At line:1 char:1
+ xpm init --template @xpack/hello-world-template@latest --property lan ...
+ ~~~
+ CategoryInfo : SecurityError: (:) [], PSSecurityException
+ FullyQualifiedErrorId : UnauthorizedAccess
The terminal process "C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe -Command xpm init --template @xpack/hello-world-template@latest --property language

then run the following command in a PowerShell terminal:

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope CurrentUser

For more details please read the Microsoft about_Execution_Policies page.

Cleanups (node/npm)

If installed as recommended via setup, node can be uninstalled via the Microsoft specific mechanisms.

For a thorough cleanup, please note that npm uses the following two folders to install global packages:

  • %APPDATA%\Roaming\npm
  • %APPDATA%\Local\npm-cache

Install xpm

xpm is also a portable Node.js command line application.

On macOS and GNU/Linux, if you followed the Quick instructions, it is already installed. Otherwise, to install it, follow the steps in the xpm install page.

If you're confident and prefer a shortcut, run the following command:

npm install -location=global xpm@latest

Miscellaneous

The official page explaining how to install npm in a custom folder is Resolving EACCES permissions errors when installing packages globally.

For less common platforms, you can install from unofficial builds, or to compile it from sources. For more details, see the Node.js downloads page.