> Markdown version of [Migration Guide for Component Add-ons](https://vaadin.com/docs/v14/flow/upgrading/v10-13/v14-addon-guide). Section index: [llms.txt](https://vaadin.com/docs/v14/flow/llms.txt)

# 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](https://vaadin.com/docs/v14/flow/upgrading/v10-13.md) 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.

## <a id="supporting-both-npm-and-compatibility-modes-with-your-add-on"></a>Supporting Both npm and Compatibility Modes with Your Add-on

> **Note:** Compatibility Mode is no longer supported from Vaadin 14.12 onwards.

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](https://vaadin.com/docs/v14/flow/creating-components/tutorial-component-composite.md) , 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.

## <a id="mandatory-steps"></a>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](https://vaadin.com/docs/v14/flow/upgrading/v10-13.md#install.npm)). 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](https://vaadin.com/docs/v14/flow/upgrading/v10-13.md#add-vaadin-maven-plugin) 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)

## <a id="migrating-an-add-on-with-external-frontend-dependencies"></a>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.

### <a id="migrating-from-webjars-to-npm-packages"></a>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:

```xml
<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:

```java
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](https://www.npmjs.com/).

### <a id="migrating-from-html-imports-to-js-modules"></a>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:

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

### <a id="migrating-javascript-imports"></a>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")`.

> **Note:** The "frontend://" protocol for frontend file imports is not used in the npm mode because it is not needed.

## <a id="migrating-add-ons-with-local-frontend-resources"></a>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](https://vaadin.com/docs/v14/flow/upgrading/v10-13.md#p2.p3.migration), 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`.

### <a id="location-and-importing-of-local-html-js-files"></a>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.

> **Note:** Any "vanilla" CSS files (imported with the `@StyleSheet` annotation) don’t need migration to be supported in Vaadin 14 npm mode.

## <a id="miscellaneous-changes-related-to-migration"></a>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](https://github.com/vaadin/skeleton-starter-flow/pull/189/files)

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

## <a id="examples-of-component-add-on-migration-to-14"></a>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](https://github.com/gatanaso/multiselect-combo-box-flow/compare/V13%2E%2E%2E2.0.0)

- An example of a web component integration with only local template files migrating from HTML imports to JS modules: [infinite-grid npm support](https://github.com/capeisti/infinite-grid/compare/0.1%2E%2E%2Ea48f3ba0384972fd155c60fc4ab459f8d4d8ad71)

- 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](https://github.com/capeisti/infinite-grid/compare/0.1%2E%2E%2E0.2)

`00887442-8A67-4F61-89E2-EE48D2FAB3C0`
