Node.js¶

Introduction¶

Node.js is a JavaScript runtime, commonly used to build servers and command line tools. We provide the node, npm and npx commands, so you can build, run, and install Node.js applications.

Warning:

Node.js applications belong in your home directory, not in your document root.

Versions¶

We provide Node.js 22, 24, and 26. The default is Node.js 24.

Available versions¶

List the available major versions and the current default. Example output:

[isabell@moondust ~]$ uberspace tool nodejs version list
  Name     Version   Default
 ────────────────────────────
  nodejs   22        False
  nodejs   24        True
  nodejs   26        False

The Default column shows our default, not your selected version. To check the version your node command currently uses, run the following. Example output:

[isabell@moondust ~]$ node --version
v24.21.0

The exact minor and patch version can change with updates.

Change version¶

Select the major version required by your application. For example, to use Node.js 22:

[isabell@moondust ~]$ uberspace tool nodejs version set 22
OK: Set version of Node.js to 22
OK: The version of Node.js is now set to 22
[isabell@moondust ~]$ node --version
v22.23.2

This is example output.

The selection applies to your whole Asteroid, including the provided node, npm, and npx commands. You do not need to log in again. Check the requirements of all your Node.js applications before changing it.

To switch to our current default version, use default. Example output:

[isabell@moondust ~]$ uberspace tool nodejs version set default
OK: Set version of Node.js to 24
OK: The version of Node.js is now set to 24

Running applications¶

Already running applications keep using the version they started with. Restart your systemd user service after changing versions, replacing my-app with your service name:

[isabell@moondust ~]$ systemctl --user restart my-app.service

This command produces no output on success. Services that use the provided node, npm, or npx commands will use the selected version when they next start.

Dependencies containing native addons may need to be rebuilt or reinstalled after switching major versions. Follow your application's installation instructions before restarting it.

Connection to webserver¶

In order to make your application accessable from the outside, you need to connect it to the webserver, using a web backend.

Please note that your application must listen on the IP 0.0.0.0. You can choose any port between 1024 and 65535.

npm¶

npm is Node.js' package manager, used to install and manage additional packages.

Use it as usual inside a project to manage that project's dependencies:

[isabell@moondust ~]$ cd my-project
[isabell@moondust my-project]$ npm install express

You can also install command line tools globally:

[isabell@moondust ~]$ npm install -g cowsay

The resulting command (cowsay in this example) is installed to ~/.local/bin, which is already on your $PATH.