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 vaadin.pnpm.global=true
, 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.
Note |
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 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.flow.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 this only works for production mode.
<plugin>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-maven-plugin</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<goals>
<goal>build-frontend</goal>
</goals>
</execution>
</executions>
<configuration>
<pnpmEnable>false</pnpmEnable>
</configuration>
</plugin>