Configuring npm/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.

Local and Global Installation

Vaadin uses npx, the node package runner to download and use a compatible version of pnpm. It specifies the version using a version specifier, such as pnpm@5.18.10.

If you have installed pnpm globally (with npm install -g pnpm) and set up the configuration parameter, the installed version is used unless it is determined to be too old. Note that Vaadin requires pnpm 5 or newer.

Install a Custom Package

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:

npx pnpm add mobx

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

pnpm add mobx

If you have already installed an older version of pnpm globally, the above command runs the old version. In such case, either upgrade the globally installed pnpm or pass a version specifier to npx, for example, pnpm@5.18.10, instead of pnpm. See the pnpm website for more information about available commands and flags.

Vaadin expects transitive platform dependencies to be available directly under node_modules. In Vaadin versions earlier than 19 that use pnpm, the --shamefully-hoist flag must be explicitly given to pnpm during package installation: pnpm i --shamefully-hoist mobx.

Custom Packages That Need Post Install Scripts

No postinstall scripts for npm/pnpm packages are run by default. There are known incidents of new package versions containing malware which have abused postinstall scripts. Not running them removes that security risk.

Some legitimate packages still use postinstall scripts and rely on them to work properly. For internal dependencies, Vaadin runs the postinstall scripts automatically.

You can allow custom packages to run postinstall scripts if needed. For development mode, add the packages as a comma-separated list to the vaadin.npm.postinstallPackages system property.

For production builds, add the <postinstallPackages> Maven/Gradle configuration property.

Switch Between npm and pnpm

pnpm (also known as performant npm) is used as the default frontend package manager instead of npm. The benefit of pnpm is that it uses a shared repository, which reduces the build time.

If pnpm is not installed globally the framework will install it locally using npm. 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.

It’s still possible to use npm. To switch to npm you can set the vaadin.pnpm.enable system property to false.

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

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

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

or use the traditional web.xml file

<?xml version="1.0" encoding="UTF-8"?>
  id="WebApp_ID" version="3.0"




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 this only works for production mode.