Skip to content

docs: frame Getting Started around Java - #6475

Merged
peholmst merged 4 commits into
mainfrom
claude/docs-getting-started-framing
Oct 23, 2026
Merged

docs: frame Getting Started around Java#6475
peholmst merged 4 commits into
mainfrom
claude/docs-getting-started-framing

Conversation

@peholmst

@peholmst peholmst commented Oct 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

What

Reframes the Getting Started section around Java. An application with a Vaadin UI is a regular Java application, and Java skills are all you need to be productive. CSS, JavaScript, and TypeScript help but aren't required.

The section is now platform-neutral. It says Vaadin works with Spring Boot, Quarkus, Jakarta EE servers, and plain servlet containers. The Quick Start and the starters use Spring Boot because it's the easiest platform to start with. The Tutorial is the exception: it's presented as building a Spring Boot application with a Vaadin UI.

Only the framing changes. Content, URLs, code, and the page-title / meta-description front matter are untouched.

This is the Getting Started counterpart to #6468, which reframed Building Apps. That section leans more heavily into Spring Boot.

Main changes

  • Front page: new opening paragraphs on the Java framing, the skills you need, and the supported platforms.
  • Quick Start:
    • Says HTML, CSS, and JavaScript help later, but the Quick Start needs only Java.
    • The note about the Spring Boot skeleton says the view code is the same on Quarkus or Jakarta EE.
    • "A Vaadin application is a regular Java application" is now "An application with a Vaadin UI is a regular Java application".
  • Tutorial:
    • The intro says you build a Spring Boot application with a Vaadin UI, and that you don't need to know Spring Boot beforehand.
    • It says the only frontend code is four short CSS rules in one step.
    • The setup page and the closing summary use the same wording.
  • Development Environment:
    • You need the same tools as for any Java application. You don't install frontend tools, because Vaadin downloads Node.js itself.
    • The run and import pages say "your application" and "your project".
    • The command-line run instruction is an example for Spring Boot projects.
    • The VS Code Spring Boot extension is recommended only for Spring Boot applications.
  • Starters:
    • The index page says which starters create Spring Boot projects, and that the templates cover Quarkus, Jakarta EE, and plain servlet containers.
    • The templates page warning now names only the Tutorial and Building Apps as Spring Boot-specific.
  • Renamed pages:
    • "Expand Your Vaadin Project" is now "Expand Your Application".
    • "Starting a Vaadin Project with Gradle" is now "Using Vaadin with Gradle".
    • "Different Ways of Starting a Project" drops "Vaadin".
    • Link text is updated, including the link to the Gradle page from Building Apps' Project Structure page.
  • Two section headings changed ("Bootstrap a Project" and "Creating a Project"). Nothing links to their old anchors.

First-run fixes

A third commit fixes friction that a review of Getting Started found. The review read the section as a Java student and as an experienced Spring Boot developer.

  • Windows: commands use .\mvnw, which works in both PowerShell and cmd.
  • IntelliJ IDEA: described as one product that's free to use. The separate Community Edition was discontinued in 2025.3, and basic TypeScript support is now free.
  • Spring Boot: the tutorial intro no longer promises to explain Spring Boot. It points to the Spring Boot documentation instead.
  • JDK: the Quick Start and Tutorial say how to check your JDK version. Tutorial setup shows the error you get when the build uses an older JDK.
  • Restart reminders: added at the three steps that change a repository interface or the data model.
  • Port 8080: the Quick Start tells readers to stop its production JAR, so it doesn't keep the port busy for the Tutorial.
  • Version note: the "Vaadin 25.3.2 or Later Required" note is removed from Edit Details.
  • Version problem in Add Data: now explained as the cost of reusing a mutable object across saves, not as "a mismatch between how Spring Data and Vaadin assume data objects should be used". Its section heading "Work Around the Version Bug" is now "Save a Copy of the Product". Nothing links to the old anchor.

The larger changes the review suggested for the Tutorial are in #6476.

Quick Start references

On /docs/latest, the Quick Start currently redirects to vaadin.com/quickstart, as part of a marketing experiment. The docs Quick Start is still served under /docs/next. A fourth commit makes the pages that send readers to the Quick Start accurate for both versions:

  • They no longer promise "about 10 minutes" or "your first view". The marketing Quick Start says 5 minutes and changes the Task List starter instead.
  • Tutorial setup no longer assumes which view the Quick Start created.
  • Tutorial setup tells readers to stop a Quick Start application that's still running, since both use port 8080.

Notes for reviewers

  • A link in the Flow reference (flow/configuration/gradle.adoc) still says "Creating a Vaadin Project", which was a heading on the Gradle page. The link works, and it's left for a later pass.
  • The discontinued Vaadin Start Playground page is unchanged.
  • Vale reports no new alerts. I didn't run the full DS Publisher build.

🤖 Generated with Claude Code

peholmst and others added 2 commits October 23, 2026 14:00
@peholmst @claude
docs: frame Getting Started around Java
2134ed5 
Getting Started described the reader's application as a "Vaadin
application". Present it as a regular Java application whose UI is
built with Vaadin instead, and say that Java skills are enough to be
productive: CSS, JavaScript, and TypeScript help but aren't required.

Keep the section platform-neutral. Vaadin works with Spring Boot,
Quarkus, Jakarta EE servers, and plain servlet containers; the Quick
Start and the starters use Spring Boot because it's the easiest to start
with, and the Tutorial builds a Spring Boot application with a Vaadin
UI.

Only the framing changes. Content, URLs, code, and the page-title and
meta-description front matter stay as they are.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@peholmst @claude
docs: use the new title of the Gradle starter page in a link
2980d01 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Oct 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Preview Deployment

This PR has been deployed for preview.

URL: https://docs-preview-pr-6475.fly.dev

Changed pages

Added content is highlighted in green; removed content is marked in red on each page.

Built from 1fd9b18

@peholmst peholmst mentioned this pull request Oct 23, 2026
Open
@peholmst @claude
docs: fix first-run friction found in a Getting Started review
3388d11 
- Use `.\mvnw` on Windows, which works in both PowerShell and cmd.
- Describe IntelliJ IDEA as one product that's free to use, since the
  separate Community Edition was discontinued in 2025.3.
- Stop promising that the tutorial explains Spring Boot; point to the
  Spring Boot documentation instead.
- Tell readers how to check their JDK version, and what the error looks
  like when the build uses an older JDK.
- Remind readers to restart after the steps that change a repository
  interface or the data model, as the tutorial's own rule says.
- Stop the Quick Start's production JAR so that it doesn't keep port
  8080 busy for the tutorial.
- Drop the note about Vaadin 25.3.2, which doesn't apply to a newly
  downloaded project.
- Explain the version problem in Add Data as a consequence of reusing a
  mutable object across saves, not as a mismatch between Spring Data
  and Vaadin, and name its section after the fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@peholmst peholmst added the target/v25.3 Automatically cherry-pick to the v25.3 branch label Oct 23, 2026
@peholmst peholmst mentioned this pull request Oct 23, 2026
Merged
@peholmst @claude
docs: describe the Quick Start so that both versions match
bec4ee1 
On /docs/latest, the Quick Start currently redirects to vaadin.com/quickstart
as part of a marketing experiment. That page builds on the Task List
starter instead of an empty project, and says it takes 5 minutes. Pages
that send readers to the Quick Start no longer promise a time of 10
minutes or a first view of their own, and the Tutorial setup no longer
assumes which view the Quick Start created. It also tells readers to stop
a Quick Start application that's still running, since both use port
8080.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@peholmst
peholmst merged commit 005862b into main Oct 23, 2026
10 of 11 checks passed
@peholmst
peholmst deleted the claude/docs-getting-started-framing branch October 23, 2026 12:24
peholmst added a commit that referenced this pull request Oct 23, 2026
@peholmst @claude
docs: add Getting Started page for adding Vaadin to an existing appli…
746b146 
…cation (#6477)

## 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.

- **Spring Boot with Maven:** the Vaadin BOM,
`vaadin-spring-boot-starter`, optional `vaadin-dev`, and
`vaadin-maven-plugin` with `build-frontend`. Then a first `@Route` view
that gets an existing Spring service through constructor injection, and
how to run the application.
- **REST controllers:** with the default root mapping, Spring MVC
controllers take precedence and Vaadin gets the remaining requests.
Covers `vaadin.url-mapping` and `vaadin.exclude-urls`, and links REST
API Alongside Vaadin.
- **Spring Security:** put `VaadinSecurityConfigurer` in its own chain
and give the existing API chain a `securityMatcher` and `@Order`. Covers
the catch-all deny (with a link to the Actuator health check guide), the
need for access annotations such as `@PermitAll` on views, and method
security applying to calls from views.
- **JPA entities:** detached entities and `LazyInitializationException`.
`open-in-view` doesn't affect Vaadin requests, and before turning it
off, check that no REST controller relies on it. Links Entities in Flow
Views.
- **Quarkus, Jakarta EE, and Gradle:** a short paragraph each, linking
the Quarkus page (including its section on existing Quarkus
applications), CDI, and the Gradle build files.

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-tree`
against the #6475 head merges cleanly.

## Verified

- **Starter contents** (Maven Central POMs, 25.2.8 and 25.3.3):
`vaadin-spring-boot-starter` brings `vaadin-spring`,
`vaadin-core-internal` (the free components), and
`spring-boot-starter-webmvc`. `com.vaadin:vaadin` adds the commercial
components. The dependency set matches the
`skeleton-starter-flow-spring` POM.
- **Build goal** (`vaadin-maven-plugin` 25.3.3 plugin descriptor):
`build-frontend` defaults to the `prepare-package` phase.
- **Request routing** (`vaadin-spring` 25.3.4 source,
`VaadinServletConfiguration`): with root mapping, Vaadin's handler
mapping has order `LOWEST_PRECEDENCE - 1`, so controllers win. The
defaults `vaadin.url-mapping=/*` and `vaadin.exclude-urls` are in
`VaadinConfigurationProperties`.
- **View access control** (`SpringSecurityAutoConfiguration`): the
annotated view access checker is turned off unless
`VaadinSecurityConfigurer` is used. The default `anyRequest` deny and
the advice to use the configurer in only one chain come from the Vaadin
Security Configurer reference.
- **API names** (javadoc, 25.4): `VaadinSecurityConfigurer.vaadin()`,
`loginView`, `Grid()`, `addColumn(...).setHeader(...)`, and
`setItems(Collection)`.
- **Default theme:** Aura loads automatically when there's no
`AppShellConfigurator` (Themes page), so the existing application class
needs no changes.
- **Route scanning:** limited to the package of the
`@SpringBootApplication` class (Routing with Spring).
- **Links:** every xref and anchor on the new page resolves to an
existing file and section.
- **Redirects:** `npm run check-redirects` passes.
- **Vale:** no errors or warnings on the new page. The only alerts are
the two usual `Vaadin.SourceCode` suggestions for inline Java, which
CLAUDE.md asks for in short how-to snippets. On
`getting-started/index.adoc`, the exclamation-point warning and the
`Finally` suggestion were already on `main`.

Not done: no local DSP build, so the page hasn't been checked rendered.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
peholmst added a commit that referenced this pull request Oct 23, 2026
@vaadin-bot @peholmst @claude
docs: frame Getting Started around Java (#6475) (CP: v25.3) (#6480)
ec0dc1b 
Co-authored-by: Petter Holmström <petter@vaadin.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@peholmst peholmst mentioned this pull request Oct 23, 2026
Merged
peholmst added a commit that referenced this pull request Oct 23, 2026
@peholmst @claude
docs: give the Getting Started front page Learn and Evaluate paths (#…
322d191 
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

cherry-picked-v25.3 target/v25.3 Automatically cherry-pick to the v25.3 branch

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@peholmst @vaadin-bot