> Markdown version of [Adding a Vaadin Portlet Module to an Existing Multi-Module Project](https://vaadin.com/docs/v14/flow/integrations/portlet/adding-portlet-module). Section index: [llms.txt](https://vaadin.com/docs/v14/flow/llms.txt)

# Adding a Vaadin Portlet Module to an Existing Maven Multi-Module Project

This document describes how to add a new Vaadin Portlet module to a Maven multi-module project. The scenarios covered are 1) adding the Vaadin Portlet module to a Vaadin multi-module portlet project, where each portlet is packaged as a separate `WAR` file with a shared static asset `WAR`, and 2) adding the Vaadin portlet module to a non-Vaadin multi-module project, where the portlet module builds two `WARs` (one for the portlet and one for the static assets).

## <a id="1-adding-a-new-vaadin-portlet-module-to-an-existing-vaadin-multi-module-portlet-project"></a>1. Adding a New Vaadin Portlet Module to an Existing Vaadin Multi-Module Portlet Project

### <a id="prerequisites"></a>Prerequisites

This short guide is applicable when:

- you have an existing Vaadin Portlet multi-module project containing a bundle module and one or more Vaadin Portlet modules, as described in [Creating Multi-Module Portlet Project](https://vaadin.com/docs/v14/flow/integrations/portlet/creating-multi-module-portlet-project.md); and

- you have a Vaadin Portlet module (either built from scratch or based on `base-starter-flow-portlet`); and

- your objective is to integrate the new Vaadin Portlet module into the target project, so that you can build and deploy all Vaadin Portlet modules as separate `WARs` together with a shared static asset `WAR`.

### <a id="adding-submodule"></a>Make Your Vaadin Portlet Module a Submodule of the Target Project

This step is identical to adding any Maven project as a submodule of an existing multi-module project. First, copy your Vaadin Portlet module (here, `myproject-newportlet`) inside the parent module of the multi-module project (here, `myproject`). Hence, in this imaginary scenario, it will end up in `myproject/myproject-newportlet`. Then register `myproject-newportlet` as a submodule in `myproject/pom.xml`:

```xml
<modules>
    <!-- portlet modules, any order if no dependencies -->
    <module>myproject-oldportlet</module>
    <module>myproject-newportlet</module>

    <!-- static assets module, should always be after portlet modules -->
    <module>myproject-bundle</module>
</modules>
```

> **Note:** The portlet modules should be added before the static asset module (here `myproject-bundle`). The internal order of the portlet modules does not matter (unless there are project-specific interdependencies).

Also, update the parent property in the portlet module’s `pom.xml` to refer to the target project:

```xml
<parent>
    <groupId>com.myorg</groupId>
    <artifactId>myproject</artifactId>
    <version>1.0-SNAPSHOT</version>
</parent>
```

Replace names and versions as applicable to your project.

### <a id="add-the-new-portlet-as-a-dependency-of-the-static-asset-module"></a>Add the New Portlet as a Dependency of the Static Asset Module

In the `pom.xml` of your bundle module (here, `myproject/myproject-bundle/pom.xml`), add the new Portlet Module artifact under `<dependencies>` with classifier `classes`:

```xml
<dependency>
    <groupId>com.myorg</groupId>
    <artifactId>myproject-newportlet</artifactId>
    <version>1.0-SNAPSHOT</version>
    <classifier>classes</classifier>
</dependency>
```

Replace `<groupId>`, `<artifactId>` and `<version>` contents as required.

### <a id="remove-unnecessary-configuration-from-portlet-module-if-applicable"></a>Remove Unnecessary Configuration From Portlet Module (If Applicable)

If your new Vaadin Portlet module was based on `base-starter-flow-portlet`, it will contain plugins and executions which are no longer needed when the module is part of a Vaadin multi-module portlet project.

First, remove the entire `vaadin-maven-plugin` section from `pom.xml` (`artifactId` may alternatively be `flow-maven-plugin`, depending on your configuration):

```xml
<plugin>
    <groupId>com.vaadin</groupId>
    <artifactId>vaadin-maven-plugin</artifactId>
    <executions>
        <!-- ... -->
    </executions>
</plugin>
```

Next, under the `maven-war-plugin` of `pom.xml`, remove the entire execution with id `static-files`:

```xml
<execution>
    <id>static-files</id>
    <goals>
        <goal>war</goal>
    </goals>
    <configuration>
        <warName>vaadin-portlet-static</warName>
        <!-- ... -->
    </configuration>
</execution>
```

Since the target project builds its own static asset module, these are no longer needed in the portlet module. Next, we need to check that the portlet module is configured properly for inclusion in a multi-module project.

### <a id="module-configuration"></a>Configure the Added Portlet Module for the Multi-Module Project

In the `pom.xml` of the added portlet module, enable `<attachClasses>`:

```xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-war-plugin</artifactId>
    <configuration>
        <attachClasses>true</attachClasses>
    </configuration>
</plugin>
```

Additionally, we must set the location from which the resources are served by the common bundle `WAR`. In the new portlet module, ensure that the file `src/main/resources/META-INF/VAADIN/config/flow-build-info.json` exists and has the following contents:

flow-build-info.json

```js
{
  "externalStatsUrl": "/myproject-bundle/VAADIN/config/stats.json"
}
```

For portlets running in Liferay 7, it would be:

flow-build-info.json

```js
{
  "externalStatsUrl": "/o/myproject-bundle/VAADIN/config/stats.json"
}
```

The first component of the path (here, `myproject-bundle`) must match the `WAR` name of the deployed static asset `WAR`.

> **Note:** As this is a relative URL, it will target 127.0.0.1:8080. This should use the correct known URL of the bundle. For instance localhost on port 80 would be `http://127.0.0.1/myproject-bundle/VAADIN/config/stats.json`

For more information on setting up the multi-module project and packaging of static assets, see [Creating Multi-Module Portlet Project](https://vaadin.com/docs/v14/flow/integrations/portlet/creating-multi-module-portlet-project.md).

### <a id="package-and-deploy-the-war-files"></a>Package and Deploy the WAR Files

Run the following Maven command in the parent project:

`mvn package`

After the Maven build, a `WAR` file is created in the target folder of each portlet module, as well as in the bundle module: `myproject-bundle/target/myproject-bundle.war`, `myproject-oldportlet/target/myproject-oldportlet.war`, …​, `myproject-newportlet/target/myproject-newportlet.war`. To deploy, copy these files to the deployment directory of your web server or portal (`webapps` directory in Tomcat/Pluto).

## <a id="2-adding-a-new-vaadin-portlet-module-to-a-non-vaadin-multi-module-project"></a>2. Adding a New Vaadin Portlet Module to a Non-Vaadin Multi-Module Project

### <a id="prerequisites-2"></a>Prerequisites

This short guide is applicable when:

- you have an existing Maven multi-module project that is not a Vaadin Portlet multi-module project; and

- you have a Vaadin Portlet module (either created from scratch or based on the `base-starter-flow-portlet`); and

- your objective is to integrate the Vaadin Portlet module into the target project, so that you can build a portlet `WAR` and a static asset `WAR` for the Vaadin Portlet module.

### <a id="add-the-new-portlet-module-to-the-parent-pom-xml"></a>Add the New Portlet Module to the Parent pom.xml

To add the Vaadin Portlet as a submodule in the existing multi-module project, follow the instructions under [Make Your Vaadin Portlet Module a Submodule of the Target Project](#adding-submodule) in the previous section.

### <a id="ensure-that-the-new-portlet-module-builds-bundle-and-portlet-war-files"></a>Ensure that the New Portlet Module Builds Bundle and Portlet WAR Files

Ensure that the Vaadin Portlet `pom.xml` contains the `vaadin-maven-plugin` and two executions in the `maven-war-plugin` for building both the static asset bundle `WAR` and the portlet `WAR`. If your portlet module is based on `base-starter-flow-portlet`, `vaadin-maven-plugin` is added and the executions already exist with the ids `static-files` and `portlet-war`, respectively. Note that the `<warName>` of the static asset bundle must be exactly `vaadin-portlet-static` for the project to work out of the box. To use a custom bundle name, you must add a `flow-build-info.json` file containing the static asset URL as explained in [Configure the Added Portlet Module for the Multi-Module Project](#module-configuration).

### <a id="package-and-deploy-the-war-files-2"></a>Package and Deploy the WAR Files

Run the following Maven command in the parent project:

`mvn package`

After the Maven build, two `WAR` files are created: `myproject-bundle/target/vaadin-portlet-static.war` and `myproject-newportlet/target/myproject-newportlet.war`. To deploy, copy both files to the deployment directory of your web server or portal (`webapps` directory in Tomcat/Pluto).

`C640692D-F653-4D63-807B-640BECB8FA96`