Vaadin 23 to 24 Upgrade Instructions
This is a list of the changes you need to make in your application when upgrading it from Vaadin 23 to Vaadin 24, so that it compiles, runs, behaves and looks the way it did in Vaadin 23.
Vaadin 24 is based on Servlet 6.0 specifications and is compatible with the Jakarta EE 10. Vaadin encapsulates the usage of the classes from javax
/ jakarta
packages. Therefore, the application’s code doesn’t need to use servlets, directly. Nevertheless, this is needed in various cases, like accessing the cookies, setting servlet’s parameters, etc.
Vaadin 24 uses the latest Spring-boot 3.0 and Spring Framework 6.0 versions. This leads in turn to making breaking changes in Spring-based features compared to earlier Spring-boot 2.x and Spring Framework 5.x versions.
Finally, Vaadin 24 requires Java 17 and higher. This is dictated by Spring framework and newer versions of application servers.
Vaadin 24 doesn’t fundamentally change how applications are developed and behave. Still, it requires certain upgrade tasks: convert to Jakarta namespaces; upgrade Jakarta-compatible dependencies; and upgrade third-party libraries to the versions used by Spring. This migration guide highlights essentials and provides information to help with migrating your application.
To upgrade from versions before Vaadin 23, refer to the Vaadin 14 to 23 Upgrade Instructions.
Overview
Vaadin 24 upgrade requires the following essential steps:
-
Upgrade Vaadin version in the project’s
pom.xml
, checking for the latest Vaadin 24 release in GitHub. -
Convert package names to Jakarta EE 10 namespace.
-
For Spring-based applications, upgrade to Spring-boot 3.0 or Spring framework 6.0, depending on what is used in your project.
-
For non-Spring applications, upgrade the application server version to one compatible with Jakarta EE 10.
-
Upgrade third-party dependencies used in your project (such as, Maven/Gradle plugins, libraries, frameworks) to the Jakarta and Spring-compatible versions.
-
Check if your application is not using deprecated code fragments.
-
Make sure your application runs well on Java 17 runtime.
Limitations
Vaadin 24 doesn’t include Portlet and OSGi integrations as Vaadin 23 did, for two reasons:
-
The latest Portlet 3.x specification corresponds to Servlet 3.x, and it doesn’t work with Servlet 6.0.
-
Jakarta EE 10 compatible version of OSGi core runtime Apache Felix 8 is under development. Apache Karaf container is based on Apache Felix and doesn’t have a Jakarta compatible version.
Preparations
Upgrade Vaadin version in pom.xml
/ build.gradle
to the latest Vaadin 24 release like so:
<vaadin.version>24.0.0.alpha5</vaadin.version>
See the list of releases in GitHub for the latest one.
Since the pre-release is used, you have to add the following repositories:
<repository>
<id>vaadin-prereleases</id>
<url>https://maven.vaadin.com/vaadin-prereleases/</url>
</repository>
<pluginRepository>
<id>vaadin-prereleases</id>
<url>https://maven.vaadin.com/vaadin-prereleases/</url>
</pluginRepository>
Flow Context and Dependency Injection (CDI) add-on is currently using the snapshot version of DeltaSpike framework. Therefore, you need to add a snapshot repository to get this dependency if you use CDI add-on:
<repository>
<id>apache-snapshot-repository</id>
<url>https://repository.apache.org/snapshots/</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
Jakarta EE 10 Namespaces
You can use the following free tools for the package name conversion:
When being applied to a project, those tools convert Java class imports, manifests, property files and other resources to use jakarta.*
namespace when needed. Conversion instructions are in each tool’s README
file.
The last versions of IntelliJ IDEA provide migration refactoring tools, including Java EE to Jakarta EE package converter.
Make sure that Jakarta specifications in your project have the proper versions. Refer to the full list of Jakarta EE 10 specifications for more information.
Below are a few examples:
<dependency>
<groupId>jakarta.servlet</groupId>
<artifactId>jakarta.servlet-api</artifactId>
<version>6.0.0</version>
</dependency>
<dependency>
<groupId>jakarta.annotation</groupId>
<artifactId>jakarta.annotation-api</artifactId>
<version>2.1.0</version>
</dependency>
<dependency>
<groupId>jakarta.enterprise</groupId>
<artifactId>jakarta.enterprise.cdi-api</artifactId>
<version>4.0.0</version>
</dependency>
<dependency>
<groupId>jakarta.enterprise.concurrent</groupId>
<artifactId>jakarta.enterprise.concurrent-api</artifactId>
<version>3.0.0</version>
</dependency>
Spring Upgrade Instructions
Spring Boot 3 and Spring Framework 6 don’t fundamentally change how applications are developed. The main changes are around Jakarta EE 10 namespaces and supported products, Java version and the dependency upgrades and deprecations.
Spring Boot 3 / Framework 6 use new versions of third-party dependencies: Hibernate 6, Hibernate Validator 8, servlet containers - Jetty 11, Tomcat 10.1 and many others.
Spring provides the Dedicated Migration Guide for Spring-boot 3.0 and Upgrading to Spring Framework 6.x Guide.
To browse the full list of changes, please refer to Spring-boot 3.0 Release Notes and What’s New in Spring Framework 6.x.
Below is a general overview of the changes needed for Spring-based Vaadin applications:
-
Upgrade Spring to the Latest
You need to upgrade Spring versions to the latest, including the starter parent dependency:
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.0.0</version> </parent>
-
Deprecation
Deprecated
VaadinWebSecurityConfigurerAdapter
was removed since Spring no longer hasWebSecurityConfigurerAdapter
class. Use insteadVaadinWebSecurity
base class for your security configuration. Below is an example of this:@EnableWebSecurity @Configuration public class SecurityConfig extends VaadinWebSecurity { @Override public void configure(HttpSecurity http) throws Exception { // Delegating the responsibility of general configurations // of http security to the super class. It's configuring // the followings: Vaadin's CSRF protection by ignoring // framework's internal requests, default request cache, // ignoring public views annotated with @AnonymousAllowed, // restricting access to other views/endpoints, and enabling // ViewAccessChecker authorization. // You can add any possible extra configurations of your own // here (the following is just an example): // http.rememberMe().alwaysRemember(false); // Configure your static resources with public access before calling // super.configure(HttpSecurity) as it adds final anyRequest matcher http.authorizeHttpRequests().requestMatchers( new AntPathRequestMatcher("/admin-only/**")) .hasAnyRole("admin"); http.authorizeHttpRequests().requestMatchers( new AntPathRequestMatcher("/public/**")) .permitAll(); super.configure(http); // This is important to register your login view to the // view access checker mechanism: setLoginView(http, LoginView.class); } @Override public void configure(WebSecurity web) throws Exception { // Customize your WebSecurity configuration. super.configure(web); } @Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } /** * Demo UserDetailsManager which only provides two hardcoded * in memory users and their roles. * NOTE: This shouldn't be used in real world applications. */ @Bean public UserDetailsService userDetailsService( PasswordEncoder passwordEncoder) { InMemoryUserDetailsManager manager = new InMemoryUserDetailsManager(); manager.createUser(User.withUsername("user") .password(passwordEncoder.encode("userPass")) .roles("USER").build()); manager.createUser(User.withUsername("admin") .password(passwordEncoder.encode("adminPass")) .roles("USER", "ADMIN").build()); return manager; } }
In this example,
AuthenticationManagerBuilder
, used in Spring-boot 2.x, is replaced byUserDetailsService
. Andhttp.authorizeRequests().antMatchers()
are replaced byhttp.authorizeHttpRequests().requestMatchers()
.
Java Version
Vaadin 24 requires Java 17 or greater. Java 18 is also supported. Below is an example of how to deploy this version:
<properties>
<java.version>17</java.version>
<!-- OR: -->
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
</properties>
Application Servers
Before migrating, find the corresponding version of Jakarta EE 10-compatible application server used in your project. See Jakarta Compatible Products for more information.
Polymer Templates
Polymer support has been deprecated since Vaadin 18 (released in November 2020), in favor of faster and simpler Lit templates. In Vaadin 24, the built-in support for Polymer templates has been removed and is only available for Prime and Enterprise customers.
Vaadin 24 provides an automatic tool that facilitates migration from Polymer to Lit by automatically converting basic Polymer constructions into their Lit equivalents in Java and JavaScript source files.
Limitations
The converter only targets basic cases. More advanced cases, such as TypeScript source files or usage of internal Polymer API, should still be converted manually.
See Polymer to Lit converter documentation for more information about limitations and supported transformations.
Usage
Regarding usage, run the converter in your project’s root folder as follows:
mvn vaadin:convert-polymer
To convert a project that is based on versions before Vaadin 24, use the following:
mvn com.vaadin:vaadin-maven-plugin:24.0.0.alpha5:convert-polymer
Configuring
The converter accepts the following properties:
-Dvaadin.path=path/to/your/file
By default, the converter scans all files that match /.js
and /.java
and then tries to convert them to Lit.
To limit conversion to a specific file or directory, you can use the vaadin.path
property like so:
mvn vaadin:convert-polymer -Dvaadin.path=path/to/your/file
The path is always relative to your project’s root folder.
-Dvaadin.useLit1
By default, the converter transforms Polymer imports into their Lit 2 equivalents.
If your project is using Lit 1 (i.e., before Vaadin 21), you can use the vaadin.useLit1 flag to enforce Lit 1 compatible imports:
mvn vaadin:convert-polymer -Dvaadin.useLit1
-Dvaadin.disableOptionalChaining
By default, the converter transforms [[prop.sub.something]]
expressions into ${this.prop?.sub?.something}
.
If your project is using the Vaadin webpack configuration, which doesn’t support the JavaScript optional chaining operator (?.)
, you can use the vaadin.disableOptionalChaining
flag like so:
mvn vaadin:convert-polymer -Dvaadin.disableOptionalChaining
Multiplatform Runtime
Multiplatform Runtime add-on allows the use of legacy Vaadin 7 or 8 framework components in Vaadin Flow applications. In Vaadin 24, the Multiplatform Runtime artifacts to be added remain the same: mpr-v8 and mpr-v7. However, the framework server dependencies now contain a jakarta
postfix:
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-server-mpr-jakarta</artifactId>
<version>8.18.0</version>
</dependency>
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-compatibility-server-mpr-jakarta</artifactId>
<version>8.18.0</version>
</dependency>
Other legacy framework dependencies have the same names.
Maven/Gradle Plugins
Make sure that the versions of Maven plugins your project defines explicitly, are compatible with Java 17.
As an example, nexus-staging-maven-plugin
requires a minimal version 1.6.13. Gradle version 7.3 and higher is required to run on top of Java 17 (see Gradle Release Notes).
SLF4J 2.0
Vaadin 24 and Spring-boot 3.0 use SLF4J library version 2.0, which has breaking changes compared to previous versions. Check SLF4J release notes for more information.
Deprecated Code
In Vaadin 24, deprecated code has been removed. A detailed list of changes can be found at: