Documentation versions (currently viewingVaadin 8)

Vaadin 8 reached End of Life on February 21, 2022. Discover how to make your Vaadin 8 app futureproof →

Component add-on project setup how-to

This how-to walks you through a complete setup for a project for developing, building and publishing your own Vaadin UI component add-ons. The goal here is not to teach how to write an add-on, but to make the process of setting up your project environment as smooth as possible. I hope this encourages you to try building and publishing your own add-ons :)

Goals for the project environment

  • Fully automated build with Maven

  • Allow anyone to re-build your project easily regardless of the IDE:s

  • Almost instant save-build-deploy-try cycle

  • Simple, but complete, project setup

  • Project publishing to GitHub

  • Easy publishing of the results to Vaadin Directory

Install toolchain

If you do not already have the following tools in use, install them:

  • Eclipse IDE for Java EE developers from (Indigo Service Release 1 was used in this how-to)

  • Google Chrome browser from (other browsers will do, but Chrome is recommended)

  • Eclipse plugins: m4e-wtp, vaadin, egit (optional) and jrebel (optional) from Marketplace (just select Help→Marketplace…​ from the menu)

Create a new widget project

Start project creation wizard: File → New → Other…​ → "Maven Project"

Give a proper name for your project and save it under workspace. For this example I am building a list widget and name it MyList.

Ensure that your Maven archetype catalogs contain as remote catalog and select it.

Select vaadin-archetype-widget from the list.

Give a proper name for the project. I use "org.vaadin" as group id as it can be used by anyone who wants to contribute non-commercial widgets to Vaadin project and name of the widget as artifact id in this case i use "mylist" as example. For a package name use "org.vaadin.mylist".

Observe that pom.xml shows two errors. This is because m2e does not directly support gwt and vaadin -plugins. To fix the problem, choose the problems one by one and choose "ignore" quick fix. Then edit the pom.xml by changing all <ignore></ignore> tags to <execute></execute> to get the plugins to execute. Finally, clear the remaining "project configuration needs update" error with quickfix (that not surprisingly updates project configuration). In the end, pom.xml should look like this.

Refactor the name of the component you are building.

  • Instead of using MyComponent and VMyComponent, use your own name. In this example I use MyList and VMyList.

  • Also change the theme directory name from src/main/java/org/vaadin/mylist/gwt/public/mywidget to src/main/java/org/vaadin/mylist/gwt/public/mylist

  • and update the reference in MyWidgetSet.gwt.xml.

  • Also rename MyWidgetSet.gwt.xml to MyListWidgetSet.gwt.xml

  • and update references in pom.xml and web.xml.

Test that the project compiles and runs by running (Run → Run as …​ → Maven Build…​) maven goal "package jetty:run". If everything compiles fine and Jetty server starts, you can access the application at http://localhost:8080/mylist/. You should see "It works!" on the web page. Do not worry that the build takes a lot of time, we’ll get back to it in a minute.

Finally, if you prefer to use Git, create a repository for the project. You could simply choose "Share Project…​" from the Project’s Team menu. Choose "Use or create repository in parent folder" and click "Create Repository". Then, add project resources to commit. Choose pom.xml and src directory from Navigator view and select Team → Add to Index. Then add the rest of the files (.settings, .project, .classpath and target) to .gitignore with Team → Ignore. Finally, just do Team → Commit.

At this point - or later whenever you are ready for it - you can publish the project to GitHub. Just go to and create a new repository. Use MyList as the name for the repository. Then follow the instructions on the screen. In my case, I executed the following command line commands: cd /Users/phoenix/Documents/workspace/mylist; git remote add origin; git push -u origin master. You can see the results at GitHub.

Save - Build - Deploy - Try

If it takes minutes each time from code change to seeing that change on the screen, you are not going to get your component ready anytime soon. To solve the issue, we use two tools: 1) Google GWT Developer Mode and 2) JRebel. The first one is more important here as the GWT compilation step is the really slow step, but JRebel also helps as it gives you instant redeploy for the server-side changes.

To enable JRebel, open project popup menu and choose JRebel → Generate rebel.xml in src/main/java. Then click "Enable JRebel" on the JRebel tab for Maven run configuration for "jetty:run". Now when you make any changes to server-side code - for example to - hit save and reload the browser pointing to http://localhost:8080/mylist/?restartApplication, the changes are applied immediately. Even better - you can start the project with Debug As and add break points to the application.

Client-side changes are more tricky as they are compiled from Java to JavaScript by GWT. To make those changes immediately you, must be running a GWT Development Mode. This is done by running Maven goal gwt:run instead of just pointing your web browser to the running application. Note that must be running both jetty:run and gwt:run concurrently. gwt:run starts application called "GWT Development Mode". From there you can launch your browser - or cut-n-paste URL to Chrome - if that is not your default browser. When the application is started, add &restartApplication parameter to the end of the URL to ensure that the server-side of the application is reloaded each time you reload the page. In this case, the full url is Try making a change to the client-side code (for example, hitting save and reloading the page to see how everything works together. You can also run gwt:run in Debug As to debug the client-side code.

Now the "save - build - deploy - try" cycle has been reduced to almost instant for both client-side as well as server-side changes. Let the real development begin.

Developing a new component for Vaadin

Wait for an amazing idea, code like crazy, enjoy and POOOF, there it is - your own brand new component.

If you need guidance with this, Book of Vaadin is a recommended reading :)

For this example, I implemented a trivial list component. Take a look of 1.0.0 version at GitHub, but do not expect too much :) To try it out just do: git clone; mvn package; mvn jetty:run and point your web browser to http://localhost:8080/mylist/.

Packaging and submitting the widget to directory

Set the version number in pom.xml

Run Maven target "package" and you’ll have a ready made package at target/mylist-1.0.0.jar ready for upload to vaadin directory.

Go to, select UI Component and click upload.

Fill the form, preview and publish.