Happy path: Publishing a Web Component to Vaadin Add-on Directory

Did you find an excellent custom element that would make sense in your Vaadin Java web application? Maybe that is a web component that you previously published yourself in npmjs.com?

In this article, I'll go through the steps of building a Java component from a previously published custom element in npmjs.com. This article is Part 2 of a two-article series I wrote when creating a SimpleTimeline component for Vaadin. Look at Part 1, how to create and publish a web component.

This article is not exactly a tutorial; it is written more as a quick "command reference" on how to do the things needed to be done when you create, build and share a Vaadin add-on.

gh repo create MyVaadinAddon --public -p vaadin/npm-addon-template
gh repo clone MyVaadinAddon

Using Visual Studio Code and Dev Containers is an excellent way to create an isolated environment for development. I used the Alpine "Java" (16-bullseye) environment as the basis here, with Git and Maven installed.

The development of the Java component

As I said, this is not a tutorial, and I'm not going into the details of this one. An example component implementation of axa-input-text in the template needs renaming and editing. Here is an easy trick to check that you have renamed everything, you can grep through the files:

grep -r "mygroup"
grep -r "AxaInputText"
grep -r "axa-input-text"

When coming up new name some practical tips:

• Add-on name: Use Java naming. Spaces are ok, but single widget add-ons could just use the widget class name as an add-on name and project name: MyVaadinAddon.
• Maven groupId: Group ID must start with org.vaadin.addons. Just use lowercase add-on name if nothing else, like here org.vaadin.addons.myvaadinddon
• Java package name: Use the same as Maven groupId.

You can run the project simply using the following:

mvn

This runs the default mvn jetty:run goal starts a local Jetty dev server in localhost:8080

To run the browser-based integration tests, you can use:

mvn verify -Pit

This will run the tests using a special build profile with extra configuration and dependencies needed to run the browser-based tests.

Publishing to the add-on directory

Once you are ready to go public, you should first give a meaningful version number. The version number needs to follow SemVer, and it is good practice to start from 1.0.0

mvn versions:set -DnewVersion=1.0.0

Then you can build the full zip package from the project:

mvn -Pdirectory clean install

This command creates a binary package with Javadoc and source code compatible with Directory and Maven repositories.

The first time you publish, you need to go to https://vaadin.com/directory/my-components?uploadNewComponent to upload the zip file.

Finalizing the developer experience

To make the Vaadin Directory entry pleasant, some things that are good to have.

• Icon: 512x512 size image will appear in the search results and links.
• Summary: Briefly explain the use case for the component. Like 'Build a nice experience for web apps using this one-liner.'
• Code examples: Some brief yet complete code examples get your users quickly on the right track.

Have a safe trip!