Upgrade Vaadin Between Major Versions Step by Step
Upgrade a Vaadin application across a major version: baselines first, then the Vaadin BOM, compile fixes, themes, the production bundle and rollback.

A Vaadin major upgrade is mostly a platform upgrade with a small API surface, and the way to keep it from becoming a week of confusion is to change one thing at a time. The order below keeps failures separable, so when something breaks you know whether the cause is the JDK, Spring Boot or Vaadin. Examples use the Maven plugin with Spring Boot, and the same steps apply with Gradle. Always take the exact target version and its breaking changes from the release notes, since this guide fixes the procedure and not the list of API changes.
1. Clean the old version first
On the version you run today, compile with deprecation warnings visible.
./mvnw -q clean compile -Dmaven.compiler.showDeprecation=trueFix every Vaadin deprecation before moving. Methods removed in a major release were deprecated in the previous one, so this step removes most compile errors before they exist, and it does so on a codebase that still builds and tests green. It is the cheapest hour of the whole upgrade. Also run the full test suite now and record the result, so that after the upgrade you can tell new failures from old ones.
2. Raise the platform baselines alone
Upgrade the JDK and Spring Boot to whatever the target Vaadin release requires, and commit that change with the old Vaadin still in place. If this step fails, the cause is not Vaadin, and you have a smaller problem to read. A Vaadin release usually raises the minimum Java and Spring Boot versions together, and the Boot migration has its own checklist: see the Spring Boot upgrade notes for the baseline.
3. Change the Vaadin version
With the BOM, the change is one property.
<properties>
<vaadin.version>25.0.0</vaadin.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-bom</artifactId>
<version>${vaadin.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>Use the exact version from the release page rather than the placeholder shown here. The BOM keeps every Vaadin artifact aligned, as explained in Maven BOMs, which is why you never list a version on an individual Vaadin dependency. Update the vaadin-maven-plugin to the same version in the same commit, because a plugin older than the framework builds a frontend bundle that does not match the server code.
4. Delete the generated files
Vaadin generates frontend state under your project, and stale state is the most common cause of strange errors after an upgrade.
rm -rf node_modules frontend/generated package-lock.json target
./mvnw clean compileKeep hand-written files in frontend/, such as custom themes and web components, but remove the generated folder and the lock file, so npm resolves the new frontend dependencies from scratch. Check what you are deleting before running the command, especially if your project keeps anything unusual under frontend/. If package.json is committed, let the build rewrite it and review the diff.
5. Fix compile and runtime errors
Compile errors point at removed or renamed APIs, and the release notes list them with replacements. Fix them in one pass, then run the tests. Runtime errors in the browser console usually mean a custom web component or a theme variable that no longer exists, or a CSS selector that targeted an internal part of a component that moved. Click through every view that uses a custom component, and run the browser-level tests; the approach is in the testing guide. Version-specific changes, such as new defaults and removed modules, are summarised in what changed in Vaadin 25.
6. Build for production
./mvnw -Pproduction clean package
java -jar target/app.jarOpen the application from the jar, not from the development server. Development mode compiles the frontend on demand and forgives mistakes that production mode does not. A blank page here is almost always a bundle problem, and fixing the blank page walks through the checks. Also compare the bundle size with the previous release; a sudden increase usually means a new dependency pulled a large module in.
Rollback
Keep the upgrade on a branch until the production build passes and someone has used the application. If it fails late, revert the BOM and the plugin version and delete the generated folders again, since the old frontend state does not match the old versions either. The first rebuild after switching back is slow, which is normal. Deployment rollback is separate: keep the previous image available so you can return without rebuilding.
Testing the upgrade properly
A green build is not enough, because a Vaadin application's regressions are visual and behavioural. Before merging, click through the main journeys on a production build: log in, open each top-level view, use a grid with sorting and filtering, submit a form with a validation error and open every dialog. Compare screenshots with the previous version, as styling changes between majors are the commonest complaint. If you have browser tests, run them against the production bundle, not the development server.
Pay attention to the theme. A custom theme that overrides internal CSS parts or relies on a component's shadow DOM structure is the likeliest thing to break, since those internals are not part of the stable API. Replace such overrides with documented style properties where the new version offers them, and leave a comment explaining why each remaining override exists, so the next upgrade does not repeat the discovery.
A short checklist for the pull request
Record the old and new versions of the JDK, Spring Boot and Vaadin in the description. List the removed APIs you had to change. State whether the lock file and generated folders were regenerated, and attach the result of a production build. Reviewers can then check the upgrade against the release notes in minutes, without reconstructing what you did.
Communicating with users of the application
A major version upgrade can change the look and the behaviour of forms, so tell users before the release, not after. Screenshots of the main screens in the release notes cut down on support tickets. If the application has automated end-to-end tests, keep the old and new screenshots from the test run in the pull request, which gives reviewers a visual diff without opening a browser.
When not to upgrade yet
A version that is still supported does not need to move today. Upgrade when a security fix lands only in the newer line, when a dependency you need requires it, or when the support window is closing. The Vaadin upgrading guide lists the per-version steps, and the Spring Boot migration notes cover the platform side.


