Installing

This section describes the frontend development tools that Vaadin requires, and some configuration parameters related to the utilization of these.

Node.js

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

Node.js can be installed in three different ways:

  • Automatically into user’s home directory (~/.vaadin/node). Only supported by Vaadin 14.2 and newer.

  • Globally with downloaded installer or package manager (such as Homebrew). Node.js can be downloaded from https://nodejs.org/en/download/. Installing Node.js automatically installs the command-line tools npm and npx as well.

  • Project-local installation (*project_dir*/node) using the frontend-maven-plugin[https://github.com/eirslett/frontend-maven-plugin].

If Node.js is found globally, Vaadin validates that it is a supported version; if it is too old, it installs a compatible version into ~/.vaadin. We recommend using the latest LTS version. A project-local installation will always take precedence over a global or ~/.vaadin installation.

Proxy Settings for Downloading Frontend Toolchain

If you are behind a proxy server you should config your proxy settings so Vaadin can use them to download the frontend toolchain. There are four places where Vaadin read proxy settings from. You can set your proxy data in either of the followings:

  1. system properties:

  2. {project directory}/.npmrc file

  3. {user home directory}/.npmrc file

  4. environment variables

The settings are read from the list above in order. For example, if you set your proxy in system properties, other sources will be ignored. The keys that you should use to define your proxy settings are as follows:

In System Properties and 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 that a proxy should not be used for

.npmrc file structure is ini (like Java properties files). It includes pairs of key-values separated by =. Here is an example of the content of such a file with proxy settings:

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

To learn more about .npmrc file you can see official npmrc document.

Building an Application using Travis CI

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

  1. Specify the version via Travis configuration in .travis.yml.

  2. Install Node.js automatically by Vaadin

Please refer to Specifying Node.js versions in Travis docs how to specify the Node version via .travis.yml file.

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

pnpm

pnpm reduces the download time across multiple projects by caching the downloaded packages. While npm is the recommended and default package manager, Vaadin allows using pnpm as an alternative. See Switch between NPM and PNPM for instructions how to configure a Vaadin project to use pnpm.

Switch between npm and pnpm

Starting from Vaadin 14.2 pnpm (AKA performant npm) tool is available for managing frontend dependencies as a faster alternative to npm, which is still the default tool. The benefit of pnpm is that it uses a shared repository for all projects in a system which allows to reduce packages download time. Npm will download all dependencies again for every project.

If pnpm is not installed globally the framework will install it once to {home_folder}/.vaadin. The package-lock.json file which is used by npm is incompatible with pnpm and it’s removed automatically if pnpm is used. pnpm uses pnpm-lock.yaml file instead of package-lock.json. This means that any custom dependency configurations should go to pnpm-lock.yaml.

To switch between npm and pnpm you can use the vaadin.pnpm.enable system property - setting it to true switches to pnpm.

For a Spring Boot based project, you can put vaadin.pnpm.enable = true into the application.properties file.

For a plain Java or a JavaEE based project, you can use Servlet 3.0 @WebServlet annotation:

  1. @WebServlet(urlPatterns = "/*", name = "myservlet", asyncSupported = true, initParams = {
  2.         @WebInitParam(name = "pnpm.enable", value = "false") })
  3. public class CustomServlet extends VaadinServlet {
  4. }

or use the traditional web.xml file

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <web-app
  3.   id="WebApp_ID" version="3.0"
  4.   xmlns="http://java.sun.com/xml/ns/j2ee"
  5.   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  6.   xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
  7.       http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  9.   <servlet>
  10.     <servlet-name>myservlet</servlet-name>
  11.     <servlet-class>
  12.         com.vaadin.server.VaadinServlet
  13.     </servlet-class>
  15.     <init-param>
  16.       <param-name>pnpm.enable</param-name>
  17.       <param-value>false</param-value>
  18.     </init-param>
  19.   </servlet>
  21.   <servlet-mapping>
  22.     <servlet-name>myservlet</servlet-name>
  23.     <url-pattern>/*</url-pattern>
  24.   </servlet-mapping>
  25. </web-app>

To read more about how to set properties, see the Configuration Properties.

Alternatively, the property can be also set to the vaadin-maven-plugin, using pnpmEnable. Note that you need to add it for each plugin definition.

  1. <build>
  2.     <plugins>
  3.         <plugin>
  4.             <groupId>com.vaadin</groupId>
  5.             <artifactId>vaadin-maven-plugin</artifactId>
  6.             <version>${vaadin.version}</version>
  7.             <executions>
  8.                 <execution>
  9.                     <goals>
  10.                         <goal>prepare-frontend</goal>
  11.                     </goals>
  12.                 </execution>
  13.             </executions>
  14.             <configuration>
  15.                 <pnpmEnable>true</pnpmEnable>
  16.             </configuration>
  17.         </plugin>
  18.     </plugins>
  19. </build>
  20. <profiles>
  21.     <profile>
  22.         <id>production</id>
  23.         <!-- Skipping unrelated production build configuration... -->
  24.         <build>
  25.             <plugins>
  26.                 <plugin>
  27.                     <groupId>com.vaadin</groupId>
  28.                     <artifactId>vaadin-maven-plugin</artifactId>
  29.                     <executions>
  30.                         <execution>
  31.                             <goals>
  32.                                 <goal>build-frontend</goal>
  33.                             </goals>
  34.                         </execution>
  35.                     </executions>
  36.                     <configuration>
  37.                         <pnpmEnable>true</pnpmEnable>
  38.                     </configuration>
  39.                 </plugin>
  40.             </plugins>
  41.         </build>
  42.     </profile>
  43. </profiles>

Vaadin 14.2 – 14.4

Platforms 14.2 – 14.4 only support pnpm versions in the 4.4 to 4.5 range. To use the platform, there is do not need to install pnpm separately, as it is done automatically by the framework. However, if you want to add frontend packages manually to node_modules, first install pnpm version 4.5.0 globally:

  1. npm i -g pnpm@4.5.0

You can then install the desired package (in this case mobx) by running the following command in the project directory:

  1. pnpm i mobx --shamefully-hoist

The --shamefully-hoist flag is required because Vaadin expects transitive platform dependencies to be available directly under node_modules. pnpm accepts other common npm flags, such as --save and --save-dev for saving the dependency to package.json.

Vaadin 14.5+

Vaadin uses npx, the node package runner to locate (and if necessary download) a compatible pnpm version. If you have installed pnpm globally (via npm i -g pnpm), the installed version is used by default unless it is determined to be too old.

To install a custom frontend package into your project with pnpm, install Node.js globally and run pnpm using npx. For example, to install the mobx package into node_modules, run the following command in the project directory:

  1. npx pnpm i mobx --shamefully-hoist

If you have installed pnpm globally, you can alternatively call it directly:

  1. pnpm i mobx --shamefully-hoist

Vaadin requires pnpm 5 or newer. If you have already installed an older version of pnpm globally the above command runs the old version; either upgrade pnpm or pass a version specifier to npx, for example pnpm@5.15.2 instead of pnpm. The --shamefully-hoist flag is required because Vaadin expects transitive platform dependencies to be available directly under node_modules. This requirement may be relaxed in the future. pnpm accepts other common npm flags, such as --save and --save-dev for saving the dependency to package.json.

Updated 2021-03-09  Edit this article