Upgrading Guide

Instructions for upgrading to the latest Vaadin version. To run applications or components developed with Vaadin 7 or 8 inside an application written using the latest version, see Multiplatform Runtime.

Common Steps

These steps apply regardless of what version you are upgrading from.

  1. Delete node_modules folder, package.json, and pnpm-lock.yaml

  2. Edit the pom.xml file and change the Vaadin version to 20.0.0.alpha8:

    Show code

    pom.xml

    Expand code

    1. <vaadin.version>20.0.0.alpha8</vaadin.version>
    Tip
    View full pom.xml
    Click the “Expand code” button to view a complete reference pom.xml file.

  3. Update Spring Version (Spring-based projects only).

    Vaadin is compatible with Spring 5.2.0 or newer, and Spring Boot 2.2.0 or newer. If your application uses an older version of Spring, update it to a compatible version:

    Show code

    pom.xml

    Expand code

    1. <parent>
    2.     <groupId>org.springframework.boot</groupId>
    3.     <artifactId>spring-boot-starter-parent</artifactId>
    4.     <version>2.4.1</version>
    5. </parent>

  4. Run mvn clean install

Changes in Vaadin 20

These instructions apply when upgrading from a version before Vaadin 20.

Endpoints Access is Denied by Default

Previously, endpoints (methods in classes with @Endpoint annotation) without security annotations (one of @DenyAll, @PermitAll, @RolesAllowed, @AnonymousAllowed) were accessible by all authenticated users. To avoid inadvertent exposure of methods as endpoints, @DenyAll is now the default. This means meaning that you need to add explicit security annotations the endpoints you want to make accessible (either at the class level or the method level).

Default Spring Security Configuration

A default class for Spring Security configuration is available as VaadinWebSecurityConfigurerAdapter. Extend this class instead of the default WebSecurityConfigurerAdapter to automatically get a configuration that allows Vaadin specific requests to pass through security while requiring authorization for all other requests:

Show code

SecurityConfiguration.java

Expand code

  1. @EnableWebSecurity
  2. @Configuration
  3. public class SecurityConfiguration extends VaadinWebSecurityConfigurerAdapter {
  5.     protected void configure(HttpSecurity http) throws Exception {
  6.         super.configure(http);
  7.         // app's own HttpSecurity configuration as needed ...
  8.     }
  10.     @Override
  11.     protected void configure(WebSecurity web) throws Exception {
  12.         super.configure(web);
  13.         // app's own WebSecurity configuration as needed...
  14.     }
  15. }

VaadinWebSecurityConfigurerAdapter configures authentication for all routes by default. Modify this behavior with your own followup configuration as needed. It also bypasses framework internal and static resources (/VAADIN/**, sw.js …​). Previously, these had to be explicitly matched and ignored in the app.

Changes in Vaadin 19

These instructions apply when upgrading from a version before Vaadin 19.

TypeScript Configuration Now Includes Frontend Path Alias

The default tsconfig.json content was changed to introduce the Frontend import path alias.

The content of the tsconfig.json file is not updated automatically if it existed before the migration.

If you do not have any own modifications in this file, you can delete the old tsconfig.json file. vaadin-maven-plugin creates the file automatically with the new defaults next time when building the project or running the development mode.

You can also manually enable Frontend import path prefix in the existing tsconfig.json file by adding the following compiler options:

Show code

tsconfig.json

Expand code

  1. {
  2.   "compilerOptions": {
  3.     ...
  4.     "baseUrl": "frontend",
  5.     "paths": {
  6.       "Frontend/*": [
  7.         "*"
  8.       ]
  9.     }
  10.   },
  11.   ...
  12. }

Generated @Id Field Is Now of Optional Type in TypeScript

A field with @Id annotation in Java is now of optional type in the generated TypeScript code. Given an entity with an id field:

Show code

Entity.java

Expand code

  1. public class Entity {
  2.     @Id
  3.     private int id;
  4. }

Now in the TypeScript files, instead of using endpoint.getEntity(entity.id), you might need to change to endpoint.getEntity(entity.id!) (if you know that the id is always set when this is called) or add a type guard to explicitly check that id is not undefined.

Ignore One More Service Worker Related Static File

You need to ignore one more static file, /sw-runtime-resources-precache.js, if you use HttpSecurity.authorizeRequests() to do role-based authorization in your security configuration as follows:

Show code

SecurityConfiguration.java

Expand code

  1. @Override
  2. protected void configure(HttpSecurity http) throws Exception {
  3.     ...
  4.     http.authorizeRequests().anyRequest().hasAnyAuthority(Role.getAllRoles());
  5.     ...
  6. }

In such case, you need to add one more file /sw-runtime-resources-precache.js to the static resource list that Spring Security bypasses:

Show code

SecurityConfiguration.java

Expand code

  1. @Override
  2. public void configure(WebSecurity web) {
  3.     web.ignoring().antMatchers(
  4.             // client-side JS code
  5.             "/VAADIN/**",
  6.             ...
  7.             // web application manifest
  8.             "/manifest.webmanifest",
  9.             "/sw.js",
  10.             "/offline-page.html",
  11.             "/sw-runtime-resources-precache.js",
  12.             ...
  13.     );
  14. }

Ignore the Service Worker Initiated Requests

Another potential Spring Security related breaking change is about using HttpSecurity.requestCache() to redirect the user to the intended page after login.

An example of using HttpSecurity.requestCache():

Show code

SecurityConfiguration.java

Expand code

  1. @Override
  2. protected void configure(HttpSecurity http) throws Exception {
  3.     ...
  4.     http
  6.     // Register our CustomRequestCache, that saves unauthorized access attempts, so
  7.     // the user is redirected after login.
  8.     .requestCache().requestCache(new CustomRequestCache())
  10.     // Restrict access to our application.
  11.     .and().authorizeRequests()
  13.     // Allow all flow internal requests.
  14.     .requestMatchers(SecurityUtils::isFrameworkInternalRequest).permitAll()
  15.     ...
  16. }

Now you need to ignore the service worker initiated requests, otherwise the access attempts are overridden by the service worker requests and Spring cannot redirect you to the intended page. This can be done by inspecting the Referer header of the request.

The SecurityUtils::isFrameworkInternalRequest() can be updated as follows to also include the service worker initiated requests:

Show code

SecurityUtils.java

Expand code

  1. static boolean isFrameworkInternalRequest(HttpServletRequest request) {
  2.     final String parameterValue = request
  3.         .getParameter(ApplicationConstants.REQUEST_TYPE_PARAMETER);
  4.     // Use Referer in header to check if it is a sevice worker
  5.     // initiated request
  6.     String referer = request.getHeader("Referer");
  7.     boolean isServiceWorkInitiated = (referer != null
  8.                 && referer.endsWith("sw.js"));
  9.     return isServiceWorkInitiated
  10.             || parameterValue != null
  11.             && Stream.of(RequestType.values())
  12.                 .anyMatch(r -> r.getIdentifier().equals(parameterValue));
  13. }

Changes in Vaadin 15

These instructions apply when upgrading from a version before Vaadin 15.

Update Main Layout/View Annotations

Several annotations typically placed on the MainLayout / MainView class must be moved to a class that implements the AppShellConfigurator interface, for example:

Show code

Java

Expand code

  1. @PWA(name = "My Vaadin App", shortName = "my-app")
  2. public class AppShell implements AppShellConfigurator {
  4. }

see set of annotations to modify the Bootstrap page for more details.

Breaking API Changes

A set of API breaking changes and their replacements are listed below:

  • Property synchronization methods in Element are replaced with similar API in DomListenerRegistration: getSynchronizedPropertyEvents, getSynchronizedProperties, removeSynchronizedPropertyEvent, removeSynchronizedProperty, addSynchronizedPropertyEvent, addSynchronizedProperty, synchronizeProperty.

  • JavaScript execution APIs executeJavaScript and callFunction in Element and Page are replaced with similarly named methods that give access to the return value executeJs and callJsFunction:

  • Miscellaneous Element methods: Element(String, boolean), addEventListener(String, DomEventListener, String…​)

  • Device and platform detection methods WebBrowser#isIOS(), WebBrowser#isIPad(), BrowserDetails#isSafariOrIOS(), BrowserDetails#isIOS(), BrowserDetails#isIPad() are replaced with method in ExtendedClientDetails: isIPad(), isIOS()

  • Methods JsModule#loadMode() and Page#addJsModule(String, LoadMode) for setting the load mode of JsModule are removed since it does not function with JavaScript modules.

  • The construction methods BeforeEvent(NavigationEvent, Class<?>) and BeforeEvent(Router, NavigationTrigger, Location, Class<?>, UI) in BeforeEvent are replaced with BeforeEvent(NavigationEvent, Class, List) and BeforeEvent(Router, NavigationTrigger, Location, Class, UI, List)

  • Methods getUrl(), getUrlBase() and getRoutes() in Router are replaced with methods getUrl(), getUrlBase() and getAvailableRoutes() in RouterConfiguration. The resolve() method in Router is replaced with the resolve() method in RouteUtil. The getRoutesByParent() method in Router is removed and has no replacement.

  • ServletHelper is replaced with HandlerHelper

  • ExecutionCanceler is replaced with PendingJavaScriptResult

  • The getBodyAttributes method in AbstractTheme, Lumo and Material is replaced with getHtmlAttributes

  • The removeDataGenerator method in HasDataGenerators and CompositeDataGenerator is removed in favor of using the registration returned from addDataGenerator(DataGenerator)

  • The methods preventsDefault and stopsPropagation in ShortcutRegistration are replaced with isBrowserDefaultAllowed ` and `isEventPropagationAllowed

  • The safeEscapeForHtml method in VaadinServlet is removed in favor of using org.jsoup.nodes.Entities#escape(String)

  • The static method getInstance in ApplicationRouteRegistry is removed in favor of the instance method.

  • The protected instance method getApplicationUrl from VaadinServlet is removed

Bootstrapping Changes

For applications upgraded from earlier versions of Vaadin, client-side bootstrapping requires replacing the usages of the V10-14 BootstrapHandler APIs with their IndexHtmlRequestHandler API counterparts as described in IndexHtmlRequestListener interface section.

The reason for this API change is that with client-side bootstrapping the initial page HTML generation is separated from loading the Flow client and creating a server-side UI instance.

  • In Vaadin 10 to 14 these two steps are combined and the index.html page includes the code and configuration needed to start the Flow client engine and link the browser page to the server-side UI instance.

  • In Vaadin 15+ with client-side bootstrapping the index.html page includes only the basic HTML markup and links to the TypeScript UI code. When adding routes in TypeScript, the UI is not guaranteed to be created, thus is optional. It will be only available after the user navigates to a server-side route.

It is also possible to continue using the bootstrapping mode in V10-14 with the useDeprecatedV14Bootstrapping flag. See how the use the flag in Configuration Properties.

Earlier Versions