Documentation

New Acceleration Kits: Kubernetes Kit and Azure Cloud Kit. Read the blog post.

Documentation

Vaadin 23 to 24 Upgrade Instructions

Upgrade your Vaadin 23 application to Vaadin 24.

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 has WebSecurityConfigurerAdapter class. Use instead VaadinWebSecurity 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 by UserDetailsService. And http.authorizeRequests().antMatchers() are replaced by http.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: