Migration Guide for Component Add-ons

This document goes through component add-on specific instructions to help you update your web component or JS library integration to support Vaadin 14 and upcoming versions.

The main migration guide describes all the main changes when coming from Vaadin versions 10 - 13 to 14, and it is recommended to read it before starting with this document.

Supporting Both npm and Compatibility Modes with Your Add-on

It is possible to run Vaadin 14 applications in either the new npm mode or in the Vaadin 10 - 13 compatibility mode. For most add-ons, it is recommended to create two different versions to support both modes in Vaadin 14. An add-on supporting only the npm mode cannot be used in the compatibility mode, and vice versa.

Any add-on version that supports Vaadin 10 - 13 should work out of the box with the compatibility mode in 14 as Bower based webjars using HTML imports are supported similarly as before. So no changes should be needed for existing Vaadin 10 - 13 add-ons to support the compatibility mode in 14.

To support the new npm mode, changes are needed for almost all component add-ons. Only server side Java-only composite components , which do not have any frontend resources or dependencies, don’t need changes to support the npm mode. For all other component add-ons, it is recommended to create a new version for the npm mode support, because typically the version published in Bower using HTML imports is not the same as the version that is published in npm and is based on JS modules. Thus the API of the e.g. web component might be different for the npm version and it could even have new features available.

If you have an add-on which does not depend on Bower webjars for frontend resources, you could support both modes with one version: in this case when going through the steps below, you should not remove the @HtmlImport and @JavaScript annotations as instructed.

Mandatory Steps

For creating the Vaadin 14 version of your component add-on, you should first:

• Bump the add-on version to the next major version

• If missing, install Node.js on your system (see instructions). If you are using Vaadin 14.2+, Node.js installation is handled automatically by the vaadin-maven-plugin so this step can be skipped.

• Bump the vaadin dependency version to the latest available 14 version (for either vaadin-bom, vaadin-core or vaadin dependencies and the vaadin-maven-plugin)

• Add the prepare-frontend goal for the Vaadin Maven Plugin as explained here for the demo & integration test modules or profiles of your add-on

• If you test your add-on in production mode, you need to switch the goal for the production build profile to build-frontend (previously two goals)

Migrating an Add-on with External Frontend Dependencies

These steps are for add-ons that integrate an external frontend dependency that is brought to the project as a webjar.

Migrating from Webjars to npm Packages

Add-ons integrating a frontend dependency using Bower-based webjars need to switch to using npm packages instead. In version 14 the npm-based frontend dependencies are declared with the @NpmPackage annotation. So for example, the following Bower webjar dependency for a web component in pom.xml file can be removed:

<dependencies>
  <!-- Other dependencies omitted for clarity -->
  <dependency>
    <groupId>org.webjars.bowergithub.polymerelements</groupId>
    <artifactId>paper-slider</artifactId>
    <version>2.0.9</version>
  </dependency>
</dependencies>

Instead it should be replaced with the following annotation on the component Java class:

import com.vaadin.flow.component.dependency.NpmPackage;
// other code omitted for clarity
@NpmPackage(value = "@polymer/paper-slider", version = "3.0.1")
public class PaperSlider extends Component { }

Notice how the web component version has updated from 2.0.9 to 3.0.1 due to the change from using HTML imports to JS modules. Another thing to notice is the @polymer/ vendor prefix in the package name, which is not always used. You can find the available npm packages from npmjs.com.

Migrating from HTML Imports to JS Modules

For component add-ons and any library integrations, all @HtmlImport annotations must be replaced with a corresponding @JsModule annotations that includes the path ot the corresponding JS module:

import com.vaadin.flow.component.dependency.JsModule;
// other code omitted for clarity
@JsModule(value = "@polymer/paper-slider/paper-slider.js")
public class PaperSlider extends Component { }

In this example, the @polymer/paper-slider maps to the package name from the value parameter in the @NpmPackage annotation in the previous chapter. The part after that is the path for the JS module file to import. To check the correct location for the module to import, you can look for the package inside the node_modules folder once the you’ve built the project once (triggering pnpm install or npm install) or you can take a look at the sources of the package in version control (eg. github repository).

Migrating JavaScript Imports

Any JavaScript files inside the webjars that were previously imported with the JavaScript annotation, like for example @JavaScript(frontend://comboBoxConnector.js"), should be now imported as @JsModule("./comboBoxConnector.js").

Migrating Add-ons with Local Frontend Resources

For any local HTML & JS frontend resources in your add-on project, you need to convert those to use JS modules and Polymer 3 as described in the main migration guide, but you don’t need to publish the frontend resources in the npm registry if you don’t want to.

After the migration to JS modules, the imports need to be changed use @JsModule annotation instead of @HtmlImport and @JavaScript.

Location and Importing of Local HTML & JS files

To be included in the add-on .jar and to be available for the frontend builds in application projects, the add-on’s frontend resources should still be located in the standard static resource directory /src/main/resources/META-INF/frontend/.

Thus a file that has been previously imported as @JavaScript("frontend://src/myComponentConnector.js") should new be imported as @JsModule("./src/myComponentConnector.js"). The same changes should be applied to @HtmlImport files that are converted to JS modules.

You can also use another resource directory, as long as you make that sure that the files end up to the above mentioned location when the add-on .jar is built.

Miscellaneous Changes Related to Migration

• You might have to update the jetty-maven-plugin version when updating to Vaadin 14. The 9.4.15.v20190215 version that has been tested to work with the “single module add-on project” that has the add-on demo in the test resources, by including the configuration <supportedPackagings><supportedPackaging>jar</supportedPackaging></supportedPackagings>

• When you your add-on depends on either vaadin or vaadin-core dependencies, you can exclude the webjars for the npm version of the add-on. This way anyone using your add-on will not have to exclude those themselves. See an example of how to exclude the webjars here

• When the prepare-frontend goal creates the package.json, package-lock.json and webpack.config.js files for your add-on project demo or integration tests modules, you should add those to version control. But these files do not need to be packaged together with the add-on.

Examples of Component Add-on Migration to 14

• An example of a web component integration migrating from a Bower based webjar to npm package and JS modules: multiselect-combo-box npm support

• An example of a web component integration with only local template files migrating from HTML imports to JS modules: infinite-grid npm support

• An example of a web component integration with only local template files adding support for npm mode on top of Vaadin 10 - 13 support: infinite-grid supporting both modes

Updated 2021-03-09  Edit this article