Installing

• Overview
• Windows
• macOS
• Linux

So, you want to develop applications using Vaadin? Awesome! Let’s get you started. First, you need to install the development tools.

Follow the development tools installation instructions for your operating system.

Instructions

Windows

Install development tools in Windows

macOS

Install development tools in macOS

Linux

Install development tools in Linux

Next Step

If you already have the tools installed, you can start a new Vaadin project.

Start a Project

Additional Tools

In addition to the tools you are required to install, some additional tools are used during development that are either optional or installed automatically for you.

Local Development Server

Vaadin applications are run by deploying them to a Java Servlet Container (a server application). All Vaadin starter packs come with an embedded servlet container that can be used during development. You can also use an external servlet container, such as Tomcat, WildFly, or WebLogic. IDEs include integration with external containers and one can make debugging easier, and more compatible if you use the same one for production.

Dependency Management

Managing Vaadin and other Java libraries can get tedious to do manually, so using a build system that manages dependencies automatically is recommended. Vaadin is distributed in the Maven central repository, and can be used with any build or dependency management system that can access Maven repositories, such as Ivy or Gradle, in addition to Maven.

The npm package manager is used for managing Vaadin frontend dependencies.

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).

• 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:

.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:

Show code

Expand code

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 .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. It is the recommended and default package manager for Vaadin projects.

You do not need to install pnpm separately. 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 install -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 add the mobx package as a dependency in package.json as well as install it into node_modules, run the following command in the project directory:

Show code

Expand code

npx pnpm add mobx

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

Show code

Expand code

pnpm add mobx

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. See the pnpm website for more information about available commands and flags.