Docs

You are viewing documentation for an older Vaadin version. View latest documentation

Docs

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

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:

@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"?>
<web-app
  id="WebApp_ID" version="3.0"
  xmlns="http://java.sun.com/xml/ns/j2ee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
      http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">

  <servlet>
    <servlet-name>myservlet</servlet-name>
    <servlet-class>
        com.vaadin.server.VaadinServlet
    </servlet-class>

    <init-param>
      <param-name>pnpm.enable</param-name>
      <param-value>false</param-value>
    </init-param>
  </servlet>

  <servlet-mapping>
    <servlet-name>myservlet</servlet-name>
    <url-pattern>/*</url-pattern>
  </servlet-mapping>
</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.

<build>
    <plugins>
        <plugin>
            <groupId>com.vaadin</groupId>
            <artifactId>vaadin-maven-plugin</artifactId>
            <version>${vaadin.version}</version>
            <executions>
                <execution>
                    <goals>
                        <goal>prepare-frontend</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <pnpmEnable>true</pnpmEnable>
            </configuration>
        </plugin>
    </plugins>
</build>
<profiles>
    <profile>
        <id>production</id>
        <!-- Skipping unrelated production build configuration... -->
        <build>
            <plugins>
                <plugin>
                    <groupId>com.vaadin</groupId>
                    <artifactId>vaadin-maven-plugin</artifactId>
                    <executions>
                        <execution>
                            <goals>
                                <goal>build-frontend</goal>
                            </goals>
                        </execution>
                    </executions>
                    <configuration>
                        <pnpmEnable>true</pnpmEnable>
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </profile>
</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:

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:

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:

npx pnpm i mobx --shamefully-hoist

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

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.

FFF4305F-458E-46D3-A7CF-0A119BA9AA6B