Vaadin 25 release is only a couple of weeks away. A traditional issue hindering testing and usage of new major Vaadin versions is add-on compatibility. To help create a quality release, testing and upgrading add-ons is one of the most urgent and helpful ways to contribute to our open-source project.
Getting Started with Testing
The easiest way to test the Vaadin 25 compatibility is to create a fresh Vaadin 25 app (e.g., clone the starter from the v25 branch) and use the add-on dependency there. If your add-on does not extensively use client-server communication, there is a good chance it works as such. Or it might be working, as long as you use the Lumo theme instead of Aura.
If it works, or works with Lumo only, be sure to update this relevant information on your add-ons directory page. It helps other developers to try out Vaadin 25 in their applications. Also, if you have tested somebody else's add-on in Vaadin 25, it is helpful to share your learnings in the add-on's discussion thread.
The fact is that many add-ons can't be compatible with both versions 24 and 25 at the same time. Thus, be ready to bump the major version and create a branch for Vaadin 24 compatible version (in case you expect that it also needs maintenance)!
Changes Needed to the Add-on Project
In many cases, upgrading to Vaadin 25 (instructions for generic Vaadin apps) is not a trivial version upgrade. And this applies to also add-on projects. As a summary, if your add-on needs changes for Vaadin 25 compatibility, you'll probably want to do at least these changes to the add-on project:
- Upgrade to Java 21 (baseline in Vaadin 25)
- Upgrade the test server
- If you are using Jetty, use version xx
- If using a Spring Boot-based test setup, upgrade to Spring Boot 4.0.0
- Include vaadin-dev to your test dependencies (to bring in the development mode/copilot). vaadin-dev is no longer coming in with vaadin-core.
We also created v25 branches for the add-on templates, so you might want to look into their changes if your test setup has issues to start. The most trivial server-side add-on changes are well summarized in this changeset.
If you have a separate war or Spring Boot project that works as a demo, generic upgrade instructions apply for that.
Dependencies
The very first thing you might notice is compilation errors because of missing classes. We have done some cleanup and modernization within Vaadin, which has allowed us to drop several transitive dependencies. In case you have utilized those transitively via Vaadin, you'll get errors.
The easiest way forward is to re-declare at your add-on level. Technically, if you have followed best practices previously, you should have done that before as well, but we know it is just handy and we have been fixing those issues by ourselves as well.
In many cases, like those related to commons-io, a better solution might be to use modern JDK APIs instead of pulling in dependencies. Below is an example of the changes we made to the framework code.
Old code utilizing Commons IO:
String text;
try (InputStream in = new FileInputStream("example.txt")) {
text = IOUtils.toString(in, StandardCharsets.UTF_8);
}
A valid Java 21 replacement:
String text = Files.readString(Path.of("example.txt"));
Some of the transitive dependencies are also upgraded, and you might need to at least change imports. For example, if you have used Jackson, you should probably move from com.fasterxml.jackson to a tools.jackson namespace.
New APIs for JSON Handling
A thing that partly falls on the previous point is moving away from the elemental.json API. The Element API in Flow now uses a more mainstream Jackson API for JSON handling. As an add-on developer, especially if you have been wrapping some existing JS library for Vaadin users, there is a high chance you have used the element.json API to transfer data between the browser and the server.
Switching to use the programmatic JSON counterparts from Jackson is rather straightforward. There is also a community-contributed helper library that can make the switch even easier in certain cases. But my suggestion is, while you have the sources open, is to move to utilize the mapping version of Jackson API, that is now directly available for Vaadin component developers.
Old "elemental JSON" code:
getElement().addEventListener("color-change", e -> {
JsonObject json = e.getEventData().getObject("event.detail");
var newValue = new RgbaColor(
(int) json.getNumber("r"),
(int) json.getNumber("g"),
(int) json.getNumber("b"),
json.getNumber("a")
);
setModelValue(newValue, true);
})
.addEventData("event.detail");
When upgraded to a version utilizing Jackson mapping (directly to the Java object), the code is shorter, cleaner, and easier to maintain:
getElement().addEventListener("color-change", e -> {
RgbColor newValue = e.getEventDetail(RgbColor.class);
setModelValue(newValue, true);
}).addEventDetail();
Lumo or Aura or Lumo and Aura
Another thing that might affect add-on components is Aura (a new theme) and the other theme-related changes. Lumo is and will still be there for a while, so the easiest option is to just declare your "add-on is only tested with Lumo". In practice, we hope that most add-ons could at least for a while support both main themes.
If you plan to test theme compatibility in your add-on, you probably want to have a mechanism to toggle between the two themes. I recently wrote a UI init event-based hack that I added to the Viritin add-ons test app. It allows you to swap between Lumo and Aura with a simple query parameter (append "?theme=aura" to show the same view with the new Aura theme).
As Aura uses a completely different namespace for its CSS variables, there might be quite a bit of work to make it work with both themes. If you want a larger example, for example, as an inspiration to your AI coding assistant, check out, for example, the Pivot Table add-ons CSS file that is fully built to support both Lumo and Aura themes.
Also suggest using @StyleSheet instead of @CssImport although not strictly required. At least it makes custom front-end bundles unnecessary in some cases.
Start Now and Ask for Help with a Low Barrier
There are probably still some rough edges in Vaadin 25, and with certain kinds of add-ons, the upgrade can be a largish effort. In case you get stuck or are too busy to work with an update of your popular add-on, do not hesitate to ask for help! We can join forces and share experiences.
We created a separate thread for Vaadin 25 add-on upgrades to the Forum where you can ask help or announce an add-on that you know already works or you would like to get upgraded.