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

The next step is to check the version:

C:\>where npm.cmd
C:\>where npm.cmd
C:Program Files
odejs
pm.cmd
C:UsersilgAppDataRoaming
pm
pm.cmd
C:\>npm --version
10.9.0
What to do if the update is not effective?

Surprisingly, checking the version may reveal the old 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). In older releases, this path was not included in the system or user path.

C:\>echo %Path%

If this is the case, 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.

Visual C++ Redistributable Files

According to Microsoft, some libraries cannot be distributed with the xPack tools and must be installed separately.

For example, the msvcp140.dll and vcruntime140.dll files are part of the Visual C++ Redistributable for Visual Studio.

Download the latest version of vc_redist.x64.exe and install it as usual.

caution

The binaries in the xPack Meson Build package use vcruntime140.dll; without these redistributables installed, the meson command will fail.

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 some scripting applications, like Node.js or Python.

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.

Long file names

Due to historical reasons, Windows restricted file paths to a maximum length of 260 characters.

This can present challenges for projects created on other platforms, where lengthy file names are more commonplace.

On Windows 10 and newer versions, the Long Paths feature can be enabled manually. For further information, please refer to the Microsoft documentation, such as the page on Maximum Path Length Limitation.

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

Clean-ups (node/npm/xpm)​

Should xpm no longer be required, you may undertake a thorough clean-up by removing the following folders:

  • %APPDATA%\Roaming\xPacks
  • %APPDATA%\Local\Caches\xPacks

Should npm no longer be required, the following folders may be removed to ensure a thorough clean-up:

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

If installed as recommended through the setup process, node can be uninstalled using Microsoft-specific mechanisms.

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.