Docs

Docs

Configuring Node.js

Installing and using Node.js locally and in CI servers.

Vaadin uses the Node.js runtime in development mode to run the Vite development server, as well as the Node.js package manager (i.e., npm) and package runner (i.e., npx) to fetch, install, and run frontend packages.

Installation

Node.js can be installed in two ways: it can be installed automatically by Vaadin into the user’s home directory, or it can be installed globally with a downloaded installer or package manager, such as Homebrew.

For global installation, Node.js can be downloaded from https://nodejs.org/en/download/. You should use the latest Long-Term Support (LTS) version.

Automatic Installation

When Vaadin installs Node.js automatically, it extracts the complete Node.js distribution into a version-specific directory under ~/.vaadin/. For example, if the requested version is v24.14.0, it’s installed into ~/.vaadin/node-v24.14.0/.

The full distribution is extracted, including node, npm, npx, and corepack on Unix, or node.exe, npm.cmd, npx.cmd, and corepack.cmd on Windows. This means you can use npm, npx, and corepack directly from the installation directory if needed. For example:

Source code
terminal
~/.vaadin/node-v24.14.0/bin/npm install some-package
~/.vaadin/node-v24.14.0/bin/npx some-tool

On Windows, the executables are in the root of the installation directory:

Source code
terminal
%USERPROFILE%\.vaadin\node-v24.14.0\npm.cmd install some-package
%USERPROFILE%\.vaadin\node-v24.14.0\npx.cmd some-tool

Since each version is installed into its own directory, multiple Node.js versions can coexist side by side under ~/.vaadin/.

Resolution Order

Vaadin resolves which Node.js installation to use in the following order:

  1. If node.folder is set, use exclusively that directory. If the Node.js binary isn’t found there, the build fails with no fallback.

  2. If require.home.node is not set, check for a suitable global Node.js on the system PATH.

  3. Check ~/.vaadin/ for the exact requested version (e.g., ~/.vaadin/node-v24.14.0/).

  4. Fall back to any compatible installed version found in ~/.vaadin/.

  5. If nothing is found, download and install the requested version into ~/.vaadin/node-v<version>/.

You can force Vaadin to skip global Node.js and use its own installation by setting the require.home.node property to true. See Configuration Properties for more information.

Custom Node.js Folder

You can point Vaadin to a specific Node.js installation directory by setting the node.folder property. When this property is set, Vaadin uses Node.js exclusively from the specified folder. No fallback to ~/.vaadin/ or global Node.js occurs — if the binary isn’t found in the given folder, the build fails.

This is useful when you want full control over which Node.js installation is used, for example in CI/CD environments or when using a Node.js version manager.

To set this as a system property:

Source code
bash
mvn jetty:run -Dvaadin.node.folder=/usr/local/custom-node

Or as a Maven plugin configuration:

Source code
XML
<configuration>
    <nodeFolder>/usr/local/custom-node</nodeFolder>
</configuration>

Proxy Settings for Downloading Frontend Toolchain

If you’re operating behind a proxy server, you should configure your proxy settings so that Vaadin can use them to download the frontend toolchain. Vaadin reads proxy settings from four places; you can set the proxy data in any of the following:

  • System properties;

  • {project directory}/.npmrc file;

  • {user home directory}/.npmrc file; or

  • Environment variables.

The settings are read in this order. For example, if you set the proxy in the system properties, the other sources are ignored.

The keys that you should use to define proxy settings are as follows:

In System Properties & Environment Variables In .npmrc Files Description

HTTP_PROXY

proxy

A proxy to use for outgoing HTTP requests.

HTTPS_PROXY

https-proxy

A proxy to use for outgoing HTTPS requests.

NOPROXY

noproxy

A comma-separated string of domain extensions for which a proxy shouldn’t be used.

The .npmrc file structure is ini — like Java properties files. It includes key-values pairs separated by the equal-sign (i.e., =).

Here’s an example of the content of such a file with proxy settings:

Source code
proxy=http://myusername:s3cr3tpassw0rd@proxyserver1:8085
https-proxy=http://myusername:s3cr3tpassw0rd@proxyserver1:8086
noproxy=192.168.1.1,vaadin.com,mycompany.com

When using PNPM and customizing the .npmrc file auto-generated by Vaadin, make sure to remove the NOTICE: this is an auto-generated file comment to prevent Vaadin to overwrite it with the default contents.

To learn more about the .npmrc file, see the official npmrc documentation.

Note

Starting from Java 8u111, basic authentication for HTTPS tunneling is disabled by default, and the download of Node.js may fail if proxy configuration provides user credentials. See "Disable Basic authentication for HTTPS tunneling" in the JDK 8u111 release notes for more on this.

To get the download to work, it’s necessary to add the -Djdk.http.auth.tunneling.disabledSchemes="" system property to the IDE application run configuration, or to the build tool — Maven or Gradle — command-line.

33A25C64-2E6E-4F6F-9C0E-5EEFD244D4B3