Repository navigation
docs: add Getting Started page for adding Vaadin to an existing application - #6477
Merged
Merged
Conversation
…cation Every Getting Started path started from a new project, so experienced developers concluded that Vaadin only suits greenfield projects. The new page shows how to add a Vaadin UI to an existing Spring Boot application built with Maven, and how it coexists with the REST controllers, Spring Security configuration, and JPA entities the application already has. Quarkus, Jakarta EE, and Gradle are covered briefly through links. Link the page from the Getting Started front page and the Starters index. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Contributor
Preview DeploymentThis PR has been deployed for preview. URL: https://docs-preview-pr-6477.fly.dev Changed pagesAdded content is highlighted in green; removed content is marked in red on each page.
Built from 7fa2cd1 |
peholmst
added a commit
that referenced
this pull request
Oct 23, 2026
…6482) ## What Restructures the Getting Started front page (`articles/getting-started/index.adoc`) so that it serves two readers: someone learning Vaadin, and someone evaluating it for a project. Before, the page sent everyone to a single Quick Start button and put the evaluation reading list in one long paragraph. It had no entry for existing applications, migration, or working with a REST API. This builds on #6475 (Java framing) and #6477 (the Existing Applications page). The opening paragraphs from #6475 are unchanged. ## The page now - **Title:** "Getting Started with Vaadin" instead of "Welcome to the Getting Started Guide!". `page-title`, `meta-description`, and `description` are unchanged. - **Learn Vaadin:** an ordered path. Quick Start, then the Tutorial (a Spring Boot application with a Vaadin UI), then Next Steps. The pointers to Development Environment and Starters stay here. - **Evaluate Vaadin:** an ordered reading list with a time estimate of about half an hour. When to Use Vaadin, How Vaadin Works at Runtime, Licensing, Support & Maintenance, and Supported Technologies. It ends with a pointer to the Architecture deep dives. - **Start from Existing Code:** a short description list for readers who already have code: - **A Java application:** Add a Vaadin UI to an Existing Application (#6477) - **A REST API or a separate backend:** REST API Alongside Vaadin, and Call a Remote Service - **A Swing application:** SwingBridge, Swing Kit, and the Modernization Toolkit - **An older Vaadin version:** the Upgrading Guide, Version Comparison, Multiplatform Runtime (Vaadin 7 and 8), and the Modernization Toolkit ## New links The page didn't link to these before: - `articles/getting-started/next-steps.adoc` - `articles/building-apps/architecture/index.adoc` - `articles/building-apps/integration/rest-api.adoc` - `articles/building-apps/integration/call-remote-services.adoc` - `articles/tools/modernization-toolkit/swing-bridge/index.adoc` - `articles/tools/swing/index.adoc` - `articles/tools/modernization-toolkit/index.adoc` - `articles/upgrading/index.adoc` - `articles/upgrading/version-comparison.adoc` - `articles/tools/mpr/index.adoc` All the other links were already there. No pages move, so no redirects are needed. ## Notes for reviewers - **Quick Start:** on /docs/latest, the Quick Start currently redirects to vaadin.com/quickstart, which is part of a marketing experiment. I checked again today, and the redirect is still there. The Quick Start item promises only "a running application that you've changed yourself, in minutes", which is true for both versions. It doesn't name a duration, a view, or a production build. - **No buttons or cards:** a docs card makes its whole area one link, so a path with several steps can't be a card. The paths are plain ordered lists, which keeps the page short. The Quick Start button is gone, so that neither path stands out more than the other. The docs front page still links straight to the Quick Start. - **Licensing:** the migration tools aren't labeled as commercial, following the practice of leaving product-to-tier mapping to vaadin.com/pricing. Their own pages carry the commercial banner. - **JSF:** no page covers migration from JSF, so the page doesn't mention it. - **Vale:** no alerts. On main, the page has one warning (the exclamation point in the title) and one suggestion. `Vaadin.Versions` is turned off around the existing-code list, because Multiplatform Runtime applies only to Vaadin 7 and 8. The Feature Pack and Upgrading pages use the same pattern. - I rendered the page body with Asciidoctor to check the lists. I didn't run the full DS Publisher build. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.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
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.
Why
Every path through Getting Started begins with a new project. Nothing covers adding Vaadin to an existing Spring Boot application that already has REST controllers, Spring Security, and JPA entities, so experienced developers conclude that Vaadin only suits greenfield projects. Most of the material already exists in the Flow reference and Building Apps, but Getting Started doesn't link to it.
What
A new page, Existing Applications (
articles/getting-started/existing-application.adoc, order 25, between Starters and Tutorial). It follows the framing from #6475: the application with a Vaadin UI is a regular Java application, Vaadin is its UI layer, and Spring Boot is recommended but not required.vaadin-spring-boot-starter, optionalvaadin-dev, andvaadin-maven-pluginwithbuild-frontend. Then a first@Routeview that gets an existing Spring service through constructor injection, and how to run the application.vaadin.url-mappingandvaadin.exclude-urls, and links REST API Alongside Vaadin.VaadinSecurityConfigurerin its own chain and give the existing API chain asecurityMatcherand@Order. Covers the catch-all deny (with a link to the Actuator health check guide), the need for access annotations such as@PermitAllon views, and method security applying to calls from views.LazyInitializationException.open-in-viewdoesn't affect Vaadin requests, and before turning it off, check that no REST controller relies on it. Links Entities in Flow Views.Links to the page:
getting-started/index.adoc: one sentence added inside the "Evaluating Vaadin for a project?" paragraph.getting-started/starters/index.adoc: one sentence after the section outline.Both links sit on lines that #6475 doesn't touch.
git merge-treeagainst the #6475 head merges cleanly.Verified
vaadin-spring-boot-starterbringsvaadin-spring,vaadin-core-internal(the free components), andspring-boot-starter-webmvc.com.vaadin:vaadinadds the commercial components. The dependency set matches theskeleton-starter-flow-springPOM.vaadin-maven-plugin25.3.3 plugin descriptor):build-frontenddefaults to theprepare-packagephase.vaadin-spring25.3.4 source,VaadinServletConfiguration): with root mapping, Vaadin's handler mapping has orderLOWEST_PRECEDENCE - 1, so controllers win. The defaultsvaadin.url-mapping=/*andvaadin.exclude-urlsare inVaadinConfigurationProperties.SpringSecurityAutoConfiguration): the annotated view access checker is turned off unlessVaadinSecurityConfigureris used. The defaultanyRequestdeny and the advice to use the configurer in only one chain come from the Vaadin Security Configurer reference.VaadinSecurityConfigurer.vaadin(),loginView,Grid(),addColumn(...).setHeader(...), andsetItems(Collection).AppShellConfigurator(Themes page), so the existing application class needs no changes.@SpringBootApplicationclass (Routing with Spring).npm run check-redirectspasses.Vaadin.SourceCodesuggestions for inline Java, which CLAUDE.md asks for in short how-to snippets. Ongetting-started/index.adoc, the exclamation-point warning and theFinallysuggestion were already onmain.Not done: no local DSP build, so the page hasn't been checked rendered.
🤖 Generated with Claude Code