This article will show you how to use Maven2 to manage your dependencies, build your Vaadin web application, and build your custom widgetset. It is assumed that the reader is already familiar with Maven2, and that Maven2 is already installed and properly configured on the system. For specific information about Maven2, please refer to the.
This page first introduces how to create a new Vaadin project with Maven2 archetypes and how to use it. Then, steps for modifying existing Maven2 projects to use Vaadin (version 6.2 or later) are given.
See the end of the page for using Vaadin versions prior to 6.2 with Maven.
CreatingaVaadinMavenproject
Create a Maven Vaadin project, for example using the archetype:
mvn archetype:generate -DarchetypeGroupId=com.vaadin -DarchetypeArtifactId=vaadin-archetype-clean -DarchetypeVersion=LATEST -DgroupId=your.company -DartifactId=project-name -Dversion=1.0 -Dpackaging=war
Replace 'your.company' with your usual groupId (if you are not familiar with the concept of groupId, please refer to the official documentation for more explanations) and'project-name' by the name of your project.
You can also create the project directly from IDEs with Maven integration (e.g. or the built-in Maven integration in NetBeans) using the archetype.
The archetype 'vaadin-archetype-clean' contains a web project skeleton with a dependency on Vaadin and a minimal Vaadin application to use as a starting point. In addition, if necessary, you can uncomment the widgetset compilation related parts in 'pom.xml' if using or integrating custom client side widgets.
There are also archetypes 'vaadin-archetype-sample' and 'vaadin-archetype-widget' which are described below.
Note: Vaadin 6.5.x reguires GWT 2.1.0
-> You will need to update gwt-maven-plugin to 2.1.0 in pom.
-> You will need to update com.google.gwt to 2.1.0 in pom.
RunningTheApplication
The generated project can be easily tested using the Jetty application server with the Maven goals'package''jetty:run'. Then navigate to 'http://localhost:8080/myprojectname', where the project name is the artefactId used when creating the project.
To run the project using Tomcat, use the Maven goal 'tomcat:run'.
UsingVaadinAdd-onswithMaven
The Maven POM button in the Vaadin Directory provides an easy way to use any add-on in your Maven project. See the for detailed instructions.
As an example, to use the add-on, edit your 'pom.xml' as follows:
... ... org.vaadin.addons confirmdialog 1.0.1
If the add-on contains a custom client-side widget, as is the case for most UI component add-ons, it is required to create and compile the widgetset before running the application. When using the'vaadin-archetype-clean' archetype, you first need to uncomment the relevant sections in your'pom.xml' (gwt-maven-plugin andvaadin-maven-plugin configuration sections as well as the dependency on GWT and the snapshot plugin repositories). Then see the for detailed instructions.
To automatically find added widgets at a later time, run the goal 'vaadin:update-widgetset' and to recompile the widgetset after updating client-side widgets or Vaadin, execute the goal'gwt:compile'.
Note that some add-ons in the directory have additional external dependencies, which are not listed in the automatically generated POM section in the directory. If the add-on author has not separately published the add-on with full dependency definitions in another Maven repository, you may need to add the additional dependency sections to your POM by hand.
OtherArchetypesandUpdatingExistingMavenProjectstoUseVaadin
UsingMaventobuildyourcustomwidgets
Generating a demo custom-widget app with the Vaadin Maven archetype
If your project uses custom GWT widgets, you will need to compile them with the GWT compiler. This can be done using the.
To set up a demo Vaadin Maven application (containing the Vaadin Color Picker demo), a Maven Archetype is available. This demo application can be used as a starting point for your own Vaadin Maven application.
Use the archetype to generate the demo project as follows:
mvn archetype:generate -DarchetypeGroupId=com.vaadin -DarchetypeArtifactId=vaadin-archetype-sample -DarchetypeVersion=LATEST -DgroupId=your.company -DartifactId=project-name -Dversion=1.0.0 -Dpackaging=war
Adding custom widgets to a Vaadin Maven application
Vaadin projects created with the above mentioned archetypes already contain the necessary definitions for compiling a widgetset. The definitions are commented out in projects created with thevaadin-archetype-clean archetype and active for projects created using thevaadin-archetype-sample or vaadin-archetype-widget archetypes. Also, an empty widgetset stub and a reference to it need to be added to the project if usingvaadin-archetype-clean - see above under the add-ons section.
If the 'vaadin-maven-plugin' is used, the widgetset (if any) can be automatically updated based on project dependencies. This is achieved with the Maven goal'vaadin:update-widgetset' followed by'gwt:compile'. Running the goalclean (or gwt:clean) prior tovaadin:update-widgetset is recommended.
Creating a Vaadin widget package project
To create and package widgets for use in other projects, use the archetype 'vaadin-archetype-widget'. The project also contains a trivial test application for the widget.
The Maven goal 'package' produces a JAR that can be added as a dependency to another Vaadin Maven project or otherwise distributed as a standalone widget package to other users.
Note that Vaadin widget packages contain the source code, which is needed for the GWT compiler. Only the client side sources are needed, but all sources are included by default in widget packages.
Using Vaadin nightly builds (snapshots) with Maven
To use Vaadin nightly builds, add the Vaadin snapshot repository to your pom.xml:
#!xml... vaadin-snapshots [http://oss.sonatype.org/content/repositories/vaadin-snapshots/ ]false true
Then refer to Vaadin e.g. as '6.3-SNAPSHOT' or '6.4-SNAPSHOT'.
Note that this repository and the Vaadin add-on repository are predefined in recent versions of the Vaadin archetypes.
UsingVaadininexistingMavenprojects
Adding Vaadin to an existing Maven project
Open the project in your IDE, and open the 'pom.xml' file. Add the Vaadin dependency to your project:
#!xml... ... com.vaadin vaadin 6.5.0
Your project can now use Vaadin. Modify your 'web.xml' as usual to add the servlet information, and set up your Application class and you're good to go!
Adding widgetset compilation to an existing Vaadin project
If using an older project or a project not created with the Vaadin archetypes, simply insert the following snippet into your'pom.xml' file. It will allow you to build your custom widgets:
#!xml... ... ... org.codehaus.mojo gwt-maven-plugin 2.1.0-1 ${project.build.directory}/${project.build.finalName}/VAADIN/widgetsets -Xmx512M -Xss1024k clean ${project.build.directory}/${project.build.finalName} true 8080 false resources compile com.vaadin vaadin-maven-plugin 1.0.1 update-widgetset ... ...codehaus-snapshots [http://nexus.codehaus.org/snapshots ]true false ... com.vaadin vaadin 6.5.0 com.google.gwt gwt-user 2.1.1 provided
With this snippet inserted, at compile time, Maven will generate your custom widget files, and put them in the proper build directory (target/artifactId-version ).
Archetypeversionsvs.Vaadinversions
| Vaadin version | Archetype - sample | Archetype - clean | Archetype - widget | |
|---|---|---|---|---|
| 6.1 | 1.0 | - | - | |
| 6.2 | 1.1 | 1.1 | 1.1 | |
| 6.3 | 1.2 | 1.2 | 1.2 | |
| 6.4 | 1.3 | 1.3 | 1.3 | |
| 6.5 | 1.4 | 1.4 | 1.4 |
Only the archetype 'vaadin-archetype-sample' versions 1.0.x are compatible with Vaadin versions prior to Vaadin 6.2. This archetype contains the color picker sample application with its own custom widget.
Most of the instructions above about adding Vaadin support to an existing Maven project also apply for older Vaadin versions. However, the Maven plugin'vaadin-maven-plugin' should not be used with older Vaadin versions.