docs: cover common Vaadin 8 to 25 migration pitfalls (#5997) (CP: v25.2) - #5998
Merged
Conversation
Based on feedback from a production Vaadin 8 → 25 migration. Each item below caused real debugging time and was either missing from the docs or hard to find from the symptom. ## Charts — `series.getConfiguration()` returns `null` New [Series and Configuration](https://github.com/vaadin/docs/blob/claude/vaadin-migration-docs-2aa714/articles/components/charts/configuration.adoc) section. A series is linked to a `Configuration` only by `addSeries()`/`setSeries()`, so reading `getConfiguration()` before that throws `NullPointerException`, and `setyAxis(YAxis)` throws `IllegalStateException`. The feedback reported this as a V25 breaking change. It isn't — `AbstractSeries` behaves identically in 24.9.7 and 25.0.0 — so it's documented as a Charts pitfall rather than in the Upgrading Guide. It still bites when migrating V8 chart code that configures series before adding them. ## Security — form login Warning against configuring form login with Spring Security's `formLogin()` instead of the configurer's `loginView()`, with the symptom (`ERR_TOO_MANY_REDIRECTS` / "Connection lost"), plus a short pointer from the `VaadinWebSecurity` migration steps in the Upgrading Guide. ## Security — the `ROLE_` prefix New "Roles & the Role Prefix" section: why `@RolesAllowed("ADMIN")` matches `ROLE_ADMIN`, why `User.roles()` works but `authorities()` doesn't, a warning that a missing prefix fails silently, and `GrantedAuthorityDefaults` for changing it. `GrantedAuthorityDefaults` had no mentions in the docs before this. ## Security — programmatic role checks The feedback proposed documenting a static `SecurityUtils` helper. `AuthenticationContext` already does that job and, unlike a static helper, strips the configured prefix instead of hardcoding `ROLE_`. Extended the Security Utilities section with the conditional-nav-item example instead, plus a note that hiding a nav item isn't a security measure. ## Upgrading — layout access denied Quoted the actual message so it's searchable, and explained how to choose the annotation. Correcting the premise slightly: the framework message already suggests the annotations (verified in `AnnotatedViewAccessChecker` for both 25.0.0 and 25.3.0-beta3), so this is about findability. Also, the feedback's advice to always use `@PermitAll` is too narrow — the layout must be at least as permissive as the views it hosts. ## Upgrading — no default theme Two accuracy adjustments to the reported symptom: the app renders with minimal *base styles*, not raw HTML, and an app with **no** `AppShellConfigurator` still falls back to Aura. The trap is specifically having one without a `@StyleSheet`, which is the upgraded-app case. ## Upgrading — keeping the upgrade scoped Short subsection in the Overview on changing only what the breaking changes require, including a note that this is worth stating explicitly to AI coding assistants. --- One feedback item is not addressed here: the primer returned by `get_vaadin_primer` shows `VaadinSecurityConfigurer.apply(http)`, which does not exist — `vaadin()` is the only factory method. That is already fixed in the MCP server release currently in QA, and the endpoint URL isn't changing, so no docs change is needed. Vale is clean on all three files (remaining alerts are pre-existing) and Asciidoctor reports no new structural warnings. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.