path: root/documentation/addons/addons-maven.asciidoc

---
title: Using Add-ons in a Maven Project
order: 2
layout: page
---

[[addons.maven]]
= Using Add-ons in a Maven Project

((("Maven", "using add-ons", id="term.addons.maven", range="startofrange")))

To use add-ons in a Maven project, you simply have to add them as dependencies in the project POM.

Most add-ons include client-side widgets, counterparts of the server-side components.
The add-on widgets will be included and compiled into the _application widget set_.
Compiling the widget set is handled by the Vaadin Maven Plugin.
It is enabled in Maven projects created from the Vaadin archetypes, as described in <<../getting-started/getting-started-overview#getting-started.overview, "Getting Started">>.

The plugin will attempt to automatically detect if you need to compile the application widget set.
It will generate a [filename]#target/generated-sources/gwt/AppWidgetset.gwt.xml# widget set descriptor, update it when necessary, and use it for compiling the widget set.

[[addons.maven.dependency]]
== Adding a Dependency

Vaadin Directory provides a Maven repository for all the add-ons in the
Directory.

. Open the add-on page in Vaadin Directory.

. Choose the version on the _left-side menu bar_.
+
image::img/directory-version.png[width=60%, scaledwidth=80%]
+
The latest version is selected by default, but you can choose another version from the drop-down menu.

. Click [guilabel]#Install# to display the dependency declarations.
+
image::img/directory-install.png[width=50%, scaledwidth=70%]
+
If the add-on is available with multiple licenses, you will be prompted to select a license for the dependency.

. Select the [guilabel]#Maven# tab.
+
image::img/directory-maven-pom.png[width=50%, scaledwidth=70%]

. Open the [filename]#pom.xml# file.
In single-module projects, you only have one, located in the root folder of the project.
In multi-module projects, open the one in your Vaadin application module.

*Eclipse IDE*:: Right-click on the [filename]#pom.xml# file and select "Open With > XML Editor".
You can also left-click it, which opens the Maven POM editor, but directly editing the XML code is usually easier.
You can also use the XML editor tab of the POM editor.

. Copy and paste the [literal]#dependency# declaration to under the [literal]#++dependencies++# element.
+
[source, xml, subs="normal"]
----
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>[replaceable]#com.vaadin.addon#</groupId>
      <artifactId>[replaceable]#vaadin-charts#</artifactId>
      <version>[replaceable]#1.0.0#</version>
    </dependency>
  </dependencies>
----
+
You can use an exact version number, as is done in the example above, or [literal]#++LATEST++# to always use the latest version of the add-on.
+
The POM excerpt given in Directory includes also a `repository` definition, but if you have used the Vaadin archetypes to create your project, it already includes the definition.

. _For commercial add-ons_, you need a license key.
+
Click [guilabel]#Activate# to buy a license, obtain a trial license key, or get the key from your Pro Tools subscription.
+
image::img/directory-activate.png[width=50%, scaledwidth=70%]
+
For official Vaadin add-ons, see <<addons-cval#addons.cval, "Installing Commercial Vaadin Add-on License">> for more information.

. _In Vaadin 7.6 and older_: You need to configure the widget set as described in <<addons.maven.compiling>>.

[[addons.maven.compiling]]
== Configuring the Application Widget Set

[NOTE]
====
The widget set is automatically configured in Vaadin 7.7 and later.
The plugin will attempt to detect any add-ons that need the widget set to be compiled.

Just note that it can take a bit time to compile.

To speed up, instead of compiling it locally, you can also use a public cloud service to compile it for you, and use it directly from a CDN service.
See <<addons.maven.modes>> for instructions.
====

In projects that use Vaadin 7.6 or older, you need to manually configure the widget set as follows.

[[addons.maven.widgetset]]
=== Configuring Widget Set Compilation

Compiling the widget set in Maven projects requires the Vaadin Maven plugin.
It is included in Maven projects created with a current Vaadin archetype.

If all is well, you are set to go.

If you have used the Vaadin archetypes to create the project, the POM should include all necessary declarations to compile the widget set.

However, if your Maven project has been created otherwise, you may need to enable widget set compilation manually.
The simplest way to do that is to copy the definitions from a POM created with the archetype.
Specifically, you need to copy the `vaadin-maven-plugin` definition in the `plugin` section, as well as the Vaadin dependencies and any relevant settings.

=== Compiling the Widget Set

The widget set compilation occurs in standard Maven build phase, such as with [parameter]#package# or [parameter]#install# goal.

*Eclipse IDE*::
 Click the *Compile Vaadin Widgetset* button in the Eclipse toolbar.
+
image::img/widgetset-compiling-toolbar.png[width=50%, scaledwidth=60%]

*Command-line*::
Simply run the `package` goal.
+
[subs="normal"]
----
[prompt]#$# [command]#mvn# package
----
+
Then, just deploy the WAR to your application server.

[[addons.maven.compiling.recompiling]]
=== Recompiling the Widget Set

The Vaadin plugin for Maven tries to avoid recompiling the widget set unless
necessary, which sometimes means that it is not compiled even when it should.
Running the [literal]#++clean++# goal usually helps, but causes a full
recompilation. You can compile the widget set manually by running the
[parameter]#vaadin:compile# goal.

*Eclipse IDE*::
 Click the *Compile Vaadin Widgetset* button in the Eclipse toolbar.

*Command-line*::
Run the `vaadin:compile` goal.
+
[subs="normal"]
----
[prompt]#$# [command]#mvn# vaadin:compile
----

=== Updating the Widget Set

Note that the `vaadin:compile` goal does not update the project widget set by searching new widget sets from the class path.
It must be updated when you, for example, add or remove add-ons.
You can do that by running the [literal]#vaadin:update-widgetset# goal in the project directory.

[subs="normal"]
----
[prompt]#$# [command]#mvn# [parameter]#vaadin:update-widgetset#
...
[INFO] auto discovered modules [your.company.gwt.ProjectNameWidgetSet]
[INFO] Updating widgetset your.company.gwt.ProjectNameWidgetSet
[ERROR] 27.10.2011 19:22:34 com.vaadin.terminal.gwt.widgetsetutils.ClassPathExplorer getAvailableWidgetSets
[ERROR] INFO: Widgetsets found from classpath:
...

----
Do not mind the "ERROR" labels, they are just an issue with the Vaadin Plugin
for Maven.

After running the update, you need to run the [literal]#++vaadin:compile++# goal
to actually compile the widget set.

[[addons.maven.modes]]
== Widget Set Modes

The application widget set is by default compiled locally.
You can also have it compiled in a public cloud service provided by Vaadin, and either use it directly from a CDN service or download it to serve it from your development server.

.Widget set modes
image::img/widgetset-modes.png[width=80%, scaledwidth=100%]

The widget set mode, defined in the project POM, determines how the widget set is compiled.

`local` (default)::
The widget set is compiled locally in your development workstation.

`cdn`::
Compilation is done in the public cloud service.
It is served directly from the CDN (Content Delivery Network) service.
+
Using CDN is recommended for development.

`fetch`::
Compilation is done in the public cloud service.
The widget set is then downloaded and deployed with the rest of the application to the application server.

The mode is set with a `vaadin.widgetset.mode` property in the [elementname]#properties# section at the beginning of the project POM.

[[addons.maven.modes.local]]
=== Local Widget Set Compilation

If add-ons are detected, an [filename]#AppWidgetset.gwt.xml# descriptor file is generated into the [filename]#generated-resources# folder, and later updated automatically.
The compiler uses the descriptor to compile the widget set, which is included in the web application archive.

.Local widget set compilation
image::img/widgetset-mode-local.png[width=80%, scaledwidth=60%]

Local compilation is needed in projects that have custom widgets or widget sets that are not available from the Maven central repository or from the Vaadin add-ons or pre-releases repositories.
Local compilation is necessary for completely offline work.

Local compilation is currently the default mode.
It is therefore not necessary to set it explicitly, unless you have made global Maven settings and want to override them in a particular project.
You can set the `local` parameter in the [elementname]#properties# section of your [filename]#pom.xml#:

[source, xml]
----
<properties>
    ...
    <vaadin.widgetset.mode>local</vaadin.widgetset.mode>
</properties>
...
----


[[addons.maven.modes.cdn]]
=== Online Widget Set Compilation and CDN

The online compilation service makes it easier to use add-on components in Vaadin applications, by avoiding compilation of widget sets locally.
It caches the widget sets, so often one is available immediately.
A widget set can combine widgets from multiple add-ons and if a particular combination does not already exist, the service automatically compiles it.

.Online widget set compilation and CDN
image::img/widgetset-mode-cdn.png[width=80%, scaledwidth=100%]

The CDN (Content Delivery Network) is a global network of web servers that serve the cached widget sets directly when you load your application in your browser.
Avoiding local compilation can speed up development significantly.
In development teams, all can use the shared widget sets immediately.

[TIP]
====
While this gives benefits, the application will not work without online connnectivity.
When you need to avoid the demo effect, either use the `local` or `fetch` mode.
====

The cloud service compiles a widget set with a given Vaadin version and a list of add-ons installed in your project.
The Maven plug-in receives a public URL where the widget set is available and generates an [filename]#AppWidgetset.java# file that configures your application to use the online version.
The file is generated to the default Java package.

[NOTE]
====
Online compilation and CDN can only be used with publicly available add-ons.
This means that the add-on dependencies must be available in the Maven central repository or in the Vaadin add-ons or pre-releases repositories.
If you have custom widget implementations or non-public add-ons in your sources, you cannot use the online compilation and CDN service.
====

==== Enabling Compilation

To enable online compilation and delivery from the CDN, set the widget set mode to `cdn` in the [elementname]#properties# section of your [filename]#pom.xml#:

[source, xml]
----
<properties>
    ...
    <vaadin.widgetset.mode>cdn</vaadin.widgetset.mode>
</properties>
...
----

When using the online compilation service, a [interfacename]#WidgetsetInfo# implementation is generated for your project; this makes it possible for your application to find the widget set from the correct location.

[NOTE]
====
*The CDN is not meant to be used in production.*

It is are meant for speeding up development for yourself and your team.
It is also useful if you maintain your source code in GitHub or a similar service, so that your globally working development team can immediately use the widget sets without need to compile them.

For production, especially in intranet applications, you should normally use the `local` or `fetch` modes.
This ensures that separating the availability of the Vaadin CDN service from availability of the application server does not add an extra point of failure.

_They can be used for production_ if your application is intended as globally available, you want to gain the global delivery benefit of the Vaadin CDN, and the availability tradeoff is not significant.
====

=== Serving Remotely Compiled Widget Set Locally

If you want to use online compilation, but still serve the files as part of your application, you can use the `fetch` mode.

.Fetching online widget set compilation
image::img/widgetset-mode-fetch.png[width=80%, scaledwidth=100%]

The Maven plugin downloads the compiled widget set into the project as it was compiled locally.
It generates an [classname]#AppWidgetset# class and used to provide a correct URL to the locally stored widget set.

To enable the fetch mode, in the [elementname]#properties# section of your [filename]#pom.xml#:

[source, xml]
----
<properties>
    ...
    <vaadin.widgetset.mode>fetch</vaadin.widgetset.mode>
</properties>
...
----

// TODO This is recommended during development, as it avoids slow local compilation and typically.

(((range="endofrange", startref="term.addons.maven")))