Documentation

Documentation

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.

Node.js can be installed in three ways: First, it can be installed automatically into the user’s home directory (i.e., ~/.vaadin/node). Second, it can be installed globally with a downloaded installer or package manager, such as Homebrew. Or you can use project-local installation (i.e., project_dir/node) using the frontend-maven-plugin.

For the second method, installing globally, Node.js can be downloaded from https://nodejs.org/en/download/. When installing Node.js, you’re installing in the process the command-line tools, npm and npx.

If Node.js is found globally, Vaadin validates that it’s a supported version. If it’s too old, it’ll install a compatible version into ~/.vaadin. You should use the latest Long-Term Support (LTS) version. Incidentally, a project-local installation always takes precedence over a global or ~/.vaadin installation.

You can force a Node.js installation in the ~/.vaadin folder via the require.home.node property. Since this sets the Maven requireHomeNodeExec parameter value, you can configure the Maven goal using <requireHomeNodeExec>true</requireHomeNodeExec>. To force node installation into the home directory in development mode, you should use the vaadin.require.home.node system property, or the require.home.node web initialized parameter.

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:

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

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.

Building an Application Using Travis CI

If you’re using Travis as a Continuous Integration server, there are two options to install a proper Node.js version:

  • Specify the version via Travis configuration in .travis.yml; or

  • Install Node.js automatically through Vaadin.

See the Specifying Node.js Versions in the Travis documentation for information on how to specify the Node version via the .travis.yml file.

You can force Node.js installation into the ~/.vaadin folder, as described in the section Configuring Node.js.

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