> Markdown version of [Integrating Web Components](https://vaadin.com/docs/v24/flow/create-ui/web-components). Section index: [llms.txt](https://vaadin.com/docs/v24/flow/llms.txt)

# Integrating Web Components

Web Components are a collection of web standards that allow you to create new HTML tags with custom names. They’re reusable and provide full encapsulation of styles and markup. See [Introduction to Web Components](https://vaadin.com/docs/v24/flow/create-ui/web-components/introduction-to-webcomponents.md) for more information on how it works. This page, however, explains how to integrate it into your projects.

To use a Web Component in Vaadin, you first have to load the HTML, JavaScript, and CSS files needed by the component. This is explained below. Then you need to employ a Java API to configure the component, from which to listen for events. See [Creating a Java API for a Web Component](https://vaadin.com/docs/v24/flow/create-ui/web-components/java-api-for-a-web-component.md) for more information on that.

The Web Component’s client-side files — typically JavaScript module files — are available using [npm](https://www.npmjs.com/), which Vaadin supports by default. It automatically installs and uses `npm` packages. It also serves the static files to the browser.

> **Tip: Using pnpm or bun instead of npm**
>
> Vaadin also supports using [pnpm](https://www.npmjs.com/package/pnpm) (known as *performant npm*) or [*bun*](https://bun.sh). See [Configuring npm/pnpm/bun](https://vaadin.com/docs/v24/flow/configuration/development-mode/npm-pnpm-bun.md) for details.

## <a id="integrating-a-js-module-into-vaadin"></a>Integrating a JS Module into Vaadin

Although you can create all of the files manually, the easiest way is to use the [Vaadin Add-on Starter](https://github.com/vaadin/addon-starter-flow). This gives you a project with all of the necessary dependencies. It also provides an `npm` import for the selected component, as well as a stub component Java class for your Web Component integration. And it gives you a Maven profile that handles everything necessary to deploy the component to Vaadin Directory.

The following is an example of annotations in the Java component class as a starter project for the [mwc-slider](https://github.com/material-components/material-web/tree/mwc/packages/slider) Web Component:

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

The `@Tag` annotation here defines the name of the HTML element. The `@JSModule` and `@NpmPackage` annotations define the import of the JavaScript module.

## <a id="adding-frontend-files"></a>Adding Frontend Files

Your component may require in-project frontend files, such as additional JavaScript modules. In which case, add them to the `src/main/resources/META-INF/frontend` directory so that they’re packaged in the component JAR if you choose to make an add-on of your component.

As a example, you might use the `@JsModule` annotation to add a local JavaScript module like so:

```java
@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. Additionally, if you run the Jetty web server from Maven (i.e., 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.

### <a id="understanding-the-project-files"></a>Understanding the Project Files

The project includes the `AddonView` component class at `src/test/java/…/AddonView.java`:

```java
@Route("")
public class AddonView extends Div {
  ...
}
```

This 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 `AddonView` and displays it at <http://localhost:8080>.

Once you’ve done all of this, your project is ready for you to proceed to creating the Java API. See [Creating a Java API for a Web Component](https://vaadin.com/docs/v24/flow/create-ui/web-components/java-api-for-a-web-component.md) 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 addon view is empty, use the browser console to verify that all files were found (i.e., no `404` errors) and then check that the component is correctly configured. See [Debugging a Web Component Integration](https://vaadin.com/docs/v24/flow/create-ui/web-components/debugging-a-web-component-integration.md) 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 easily to produce a demo `WAR` file for deployment. It’s usually better to create a separate project — or to 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 won’t work. Moreover, changes to the component aren’t automatically reflected in your demo application.

## <a id="deploying-the-add-on-to-the-vaadin-directory"></a>Deploying the Add-on to the Vaadin Directory

When you’re satisfied with the API, you can make the add-on available to everyone by deploying it to the [Vaadin Directory](https://vaadin.com/directory).

To create a directory-compatible add-on package, execute the following:

```terminal
mvn clean install -Pdirectory
```

This creates a `ZIP` file in the `target` directory.

To add your add-on to the Vaadin Directory, you’ll need to do the following:

- Login or register at <https://vaadin.com/directory>.

- Then, upload the `ZIP` file.

- Write an overview of your add-on to let others know what it can do, which browsers are supported, and any other relevant information.

When finished, you may 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 (e.g., by removing `<name></name>`), make sure to update the metadata, as well.

## <a id="creating-other-add-on-types"></a>Creating Other Add-on Types

You can also use the [Add-on Starter](https://github.com/vaadin/addon-template/archive/v24.zip) to create different kinds of add-ons (e.g., to create a data provider). To create a generic project that can be used for any add-on, do the following:

- Leave the default Web Component URL in the starter form;

- Download the project; and then

- Delete the `@NpmPackage` and `@JsModule` annotations, and the UI component class.