Documentation

You are viewing documentation for Vaadin 23. View latest documentation

Documentation

Integrating Web Components

Web Components are a collection of web standards that allow you to create new HTML tags with custom names. Web Components are reusable and provide full encapsulation of styles and markup. See Introduction to Web Components for more information.

To use a Web Component in Vaadin, you need:

  • to load the HTML/JS/CSS files needed by the component (see the instructions below);

  • a Java API to configure the component and listen to events from it. See Creating a Java API for a Web Component for more information.

The Web Component’s client-side files (typically JavaScript module files) are available using npm. Vaadin supports npm and automatically installs and uses npm packages. It also serves the static files to the browser.

The pnpm tool is used for package management instead of npm. This happens transparently.

If there is a reason to use npm instead of pnpm, you may disable pnpm (see Configuration Properties or Production Mode Plugin Goals and Parameters). pnpm improves package management in many ways. For example, it enables sharing the same packages between various projects. This avoids downloading them every time for every project, and also reduces the number of I/O operations.

Integrating a JS Module into Vaadin

Although you can create all the files manually, the easiest way is to use the Vaadin Add-on Starter. This gives you:

  • a project with all the necessary dependencies;

  • an npm import for the selected component;

  • a stub component Java class for your Web Component integration;

  • a Maven profile that handles everything necessary to deploy the component to Vaadin Directory.

Example: Annotations in the Java component class for a starter project for the mwc-slider Web Component.

@Tag("mwc-slider")
@NpmPackage(value = "@material/mwc-slider",
            version = "0.18.0")
@JsModule("@material/mwc-slider/mwc-slider.js")

  • The @Tag annotation defines the name of the HTML element.

  • The @JSModule and @NpmPackage annotations define the import of the JavaScript module.

Adding Front-End Files

Your component may require in-project front-end files, for example additional JavaScript modules. In this case, add them to the src/main/resources/META-INF/frontend directory, so that they are packaged in the component JAR if you choose to make an add-on of your component.

Example: Using the @JsModule annotation to add a local JavaScript module.

@JsModule("./my-local-module.js")

When running mvn clean install, the vaadin-maven-plugin automatically installs the npm package in node_modules and imports the JavaScript module file into the document provided to the browser.

In addition, if you run the Jetty web server from Maven (using mvn jetty:run), your project’s source code is monitored for changes to these types of annotations. Any change to @NpmPackage or @JsModule annotations triggers installation of the referenced packages and hot deployment of your application, including the new JS module imports.

Understanding the Project Files

The project includes the DemoView component class at src/test/java/…/DemoView.java.

@Route("")
public class DemoView extends VerticalLayout {
  ...
}

The project set-up is slightly unconventional to allow it to be a single-module Maven project. It uses the test folder both for the demo application and for the actual test files. When you run mvn jetty:run in the project, it deploys DemoView and displays it at http://localhost:8080.

Your project is now set up and you can go ahead and create the Java API. See Creating a Java API for a Web Component for how to do this.

Note
Web Components may not show a UI
Some Web Components don’t show a UI when they are added to the page as empty tags. If the demo view is empty, use the browser console to verify that all files were found (no 404 errors) and then check that the component is correctly configured. See Debugging a Web Component Integration for more.
Note
Project setup isn’t configured for deployment
Although the project setup is easy to use for development and testing, it doesn’t allow you to easily produce a demo WAR file for deployment. It’s usually better to create a separate project (or convert the project into a multi-module project) for this purpose. The demo files included in the starter are intended as test UIs, whereas your result should be aimed at the end user.
Important
Source monitoring doesn’t work in a multi-module project
If your project is configured as a multi-module project, for example because the base project is an older version or you have manually converted it, source monitoring doesn’t work. Moreover, changes to the component aren’t automatically reflected to your demo application.

Deploying the Add-on to the Vaadin Directory

When you are satisfied with the API, you can make the add-on available to everyone by deploying it to the Vaadin Directory.

To create a directory-compatible add-on package use:

mvn clean install -Pdirectory

  • This creates a ZIP file in the target directory.

To add your add-on to the Vaadin Directory:

  1. Go to https://vaadin.com/directory.

  2. Log in or register.

  3. Upload the ZIP file.

  4. Write an overview of your add-on to let others know:

    • what it can do;

    • which browsers are supported;

    • any other relevant information.

  5. Publish your add-on.

Users can use your add-on by copying the dependency information from the add-on page in the directory.

Note
Make sure to keep metadata up to date
The metadata used by the Vaadin Directory is defined in assembly/MANIFEST.MF, based on the project’s metadata. If you make changes to the project, for example by removing <name></name>, make sure to update the metadata as well.

Creating Other Add-on Types

You can also use the Add-on Starter to create different kinds of add-ons, for example, to create a data provider.

To create a generic project that can be used for any add-on:

  1. leave the default Web Component URL in the starter form;

  2. download the project;

  3. delete:

    • the @NpmPackage and @JsModule annotations;

    • the UI component class.