Repository navigation
Improve Getting Started and Building Apps for enterprise architecture evaluation #6288
Description
This was generated by AI during triage.
Tell us about your request
Improve the Getting Started and Building Apps documentation for experienced Java developers and architects evaluating Vaadin for an enterprise project.
The current documentation provides enough guidance to build a convincing prototype, but leaves important architectural and operational questions unanswered along the main learning path. It demonstrates developer productivity more convincingly than it explains the commitment involved in adopting and operating Vaadin.
This review is based on main at f42ae9b6a. It is a documentation assessment, not a runtime benchmark. Some gaps below are missing guidance; others are discoverability problems where relevant material already exists elsewhere.
Preserve what already works
- The quick start demonstrates components, event listeners, use of a Java library, and a production JAR.
- Building Apps contains substantial guidance on application services, DTOs versus entities, transactions, optimistic locking, database migrations, and paginated grids.
- Background jobs and server push address real concerns such as threading, cleanup, memory leaks, and excessive updates.
- Browserless testing guides cover several application frameworks and realistic interactions.
Findings, in priority order
1. Introduce the runtime model and its architectural consequences early
An evaluator needs to understand where UI state lives, what happens on a button click, what is stored per user and per tab, which interactions require server round trips, and what happens when connectivity or a session is lost.
The quick start explains that Java UI code runs on the server, and Conceptual Layers explains the UI/application distinction. Neither provides a compact operational model covering state, latency, concurrency, and deployment.
Suggested improvement: Add a prominently linked “How a Vaadin application works” explanation with a request-flow diagram, session/UI lifetimes, and practical implications. Include guidance on suitability and the situations where client-side React views are useful.
2. Surface stateful deployment and scaling tradeoffs in Architecture
The architecture section discusses monoliths, microservices, and packaging, but the Vaadin-specific consequences of scaling are more important to an adoption decision than general architectural definitions.
The distributed deployment reference already explains sticky sessions, replication, serialization constraints, and Kubernetes Kit. Architecture should lead readers to it before they make deployment assumptions.
Suggested improvement: Explain how to evaluate:
- Memory consumption per active session and realistic concurrent-user workloads.
- Interaction latency under realistic network conditions.
- User experience during node failure, scale-down, and deployment.
- Session continuity, session draining, and accepting a reload as operational choices.
Provide a practical measurement approach rather than a universal concurrency claim.
3. Complete the route from tutorial to production
Creating a production JAR is covered. Operating an application is not presented as a coherent next step.
Next Steps links to views, data, security, a real database, and agentic development, but lacks an explicit route through testing, deployment, monitoring, and failure handling. Production documentation exists under Flow Reference.
Suggested improvement: Add a “Take this application to production” path covering production builds, containers, reverse proxies and push connections, environment configuration and secrets, health checks, logs and metrics, and CI. Reuse and link existing reference material.
4. Connect security guidance to enterprise authentication and authorization
Add Login teaches in-memory authentication and refers production readers to Spring Security documentation. Connecting an enterprise identity provider is likely an early proof-of-concept task.
A concrete OAuth2/Keycloak guide already exists, including role mapping, but Add Login does not link to it.
Suggested improvement: Provide a clear route from login setup to an enterprise identity provider, role mapping, logout, and security verification. Extend the guidance beyond roles with an example of record-level authorization (“this user may edit this customer”) and guidance or explicit scope boundaries for tenant isolation.
Protect Services also instructs readers to test method security while saying that the corresponding guide is not yet written. Complete that handoff.
5. Offer a faster evaluation route and a clear tutorial conclusion
The tutorial includes useful explanations, complete code per step, and realistic concerns such as optimistic locking. However, it asks for 20–45 minutes per step, and the reviewed tutorial pages do not link to a runnable finished tutorial repository.
The tutorial ends with a promise of more steps, while Building Apps opens with a work-in-progress notice. Together these weaken confidence in the completeness of the recommended development path.
Suggested improvement: Give the tutorial a clearly bounded outcome and useful conclusion. Provide a runnable reference application with authentication, a service boundary, a database migration, representative tests, and deployment instructions so experienced readers can inspect it before following the tutorial selectively.
6. Make commercial boundaries and maintenance considerations discoverable
An evaluator needs to distinguish capabilities available in the open-source core from commercial components, tools, operational kits, and support offerings.
Relevant information exists elsewhere: the testing reference explains that browserless testing is free and discusses TestBench, Selenium, and Playwright; Kubernetes Kit is marked commercial.
Suggested improvement: Provide an evaluation-oriented capability map and links to supported technologies, release support, upgrades, and licensing. Make technical and procurement dependencies understandable without duplicating pricing information throughout the tutorials.
7. Distinguish framework requirements from recommended defaults
Project Structure describes a Vaadin project as essentially Spring Boot and Maven, while other documentation supports plain Java, CDI, Quarkus, and Gradle. The recommended stack is reasonable, but should be explicitly identified as a recommendation.
The microservices guide says a separate API gateway is unnecessary because Vaadin can call services directly. Direct calls alone do not settle gateway requirements for routing, policy, or traffic management.
Suggested improvement: Review architectural wording to distinguish Vaadin constraints, recommended defaults, and choices that depend on the surrounding system.
Additional gaps to address or explicitly signpost
- Consuming existing remote services, including timeouts and failure handling. The current Integration guide focuses on exposing an API.
- Application-wide error handling and recovery.
- Accessibility verification and internationalization.
- A testing strategy combining service, database, browserless, and browser tests.
Proposed outcome
Create an architect’s evaluation path, reachable from Getting Started and Building Apps, that connects runtime architecture and suitability, state and scaling, enterprise identity, testing and deployment, and commercial/support boundaries.
Use this issue to coordinate the documentation improvements; the individual topics can be implemented separately.
Acceptance criteria
- An experienced Java developer can find the evaluation path from both entry points without knowing the reference documentation structure.
- The path explains Vaadin’s runtime model and the consequences of stateful UIs before deployment decisions are made.
- Existing deployment, OAuth2, testing, compatibility, and licensing material is linked at the relevant decision points.
- The tutorial has a clear conclusion and a route to a secured, tested, deployed application.
- A runnable reference application is linked for readers who want to inspect a complete example first.
- Architectural recommendations are clearly distinguished from framework requirements.
- Remaining gaps are explicitly identified, with concrete next steps rather than broad promises of future content.
If you think this issue is important, add a 👍 reaction to help the community and maintainers prioritize this issue.
Activity
peholmst commentedon Oct 8, 2026
A second review from the same persona reached the same seven findings, so this comment only adds what the issue does not yet say. It also separates the work: this issue stays the umbrella for the missing evaluation path, and the defects found in existing pages went into their own issues (listed at the end), because they can be fixed without waiting for new content.
Additions to the findings
1. Runtime model. Besides state, latency, and deployment, the model should cover the threading contract: one lock per
VaadinSession(all tabs of one user serialize), why slow work in a listener or insideUI.access()blocks that user, and that the SpringSecurityContextis not propagated to background threads. Today the last point is covered only in background-jobs/jobs.adoc, while the server-push threading pages send readers to executors and virtual threads without mentioning it. The model should also state side by side that Flow views are denied by default while React views are accessible without authentication by default.2. Scaling. Two things the current pages assume a single JVM for, without saying so: the shared-signal broadcast examples in server-push/updates.adoc and reactive.adoc (see the single-JVM note in shared-signals.adoc), and
@Scheduledjobs in Background Jobs, which run on every node. A "scaling push" guide (sticky sessions, WebSocket proxy configuration, fallback transports, replication) would fit under Server Push and link the distributed-deployment reference.3. Route to production. Overlaps #5203. Note that next-steps.adoc is currently linked from no page at all: the quick start sends readers to the tutorial, and the tutorial ends on the WIP block without a link onward. Whatever the production path becomes, it needs an entry point.
4. Enterprise authentication. SSO Kit is marked deprecated, so the evaluation path should point at oauth2.adoc and
VaadinSecurityConfigurer.oauth2LoginPage(...)and say what replaces the kit. SAML appears nowhere in the docs; if it is out of scope, say so.6. Commercial and maintenance boundaries. Supported Technologies is linked from neither section, so Java 21 and Spring Boot 4 are not stated up front. Within the two sections the only commercial markers are the AI controllers, the self-hosted MCP server, and the IDE table's star legend.
7. Requirements vs defaults. Quarkus and CDI appear only in the browserless test setup pages. starters/templates.adoc links the Quarkus and Jetty starters but not the
flow/integrations/quarkusandflow/integrations/cdiguides. Gradle has no presence in the main path and its only page is outdated for V25 (#2567, updated with specifics today).Additional gaps to add to the list
RestClient, timeouts, token propagation) and messaging are absent; Kafka is not mentioned anywhere inarticles/.spring.jpa.open-in-view,LazyInitializationException, N+1 and fetch strategies, and the memory and serialization cost of holding entities in Grid, Binder, or the session. Not covered anywhere in the two sections.ConstraintViolationExceptionback to Binder fields, or catchesOptimisticLockingFailureExceptionin a view. Bean Validation in Binder is a one-line NOTE.BeforeLeaveObserver), error and 404 views, permission-filtered menus, i18n of titles and menus.Defects in existing pages, filed separately
@EnableMethodSecurityomitted from the React method-security example; the@Ordersentence for REST filter chains is backwards.@Asynclistener; service examples without@Transactional; "call the repository from the UI" sidebars;READ_UNCOMMITTEDexamples; wrongddl-autodefault.// TODOcomments promising pages that do not exist (the concrete list behind the last acceptance criterion here).peholmst commentedon Oct 8, 2026
Which steps the tutorial is missing
Measured against what tutorial/index.adoc promises ("a complete application with a database, forms, and navigation"), three steps are missing. Everything else that came up in the review belongs in Building Apps, not here.
@Route(""). The promised "navigation" is a route parameter on that view. One step that adds a main layout with a side menu and a second, deliberately trivial view (a placeholder for orders or deliveries from the Click & Collect story) would make the promise true and teach the one structure nearly every real application has. Deep Link fits naturally after it.Two smaller omissions can be folded into existing steps rather than added: delete is the missing quarter of CRUD and fits in Edit Details as one section with a confirm dialog; login is better offered as the first Next Steps exercise against the finished application, since Add Login already exists as a guide.
Not worth adding to the tutorial: Flyway and a real database, deployment, i18n, server push, deeper validation. The tutorial already links to Building Apps for these.
Paying for the new steps
The length problem is not the step count. It is the listings. In every later step, a third to half of the page is the full-file listing at the end, and the instruction sections repeat whole classes after each small change:
If the instructions showed only the changed lines and each step kept one collapsed full listing at the end, the existing seven steps would shrink by roughly a third. That buys a shell step and a test step without making the tutorial longer than it is today.
Suggested sequence
Setup, List Data, Sort & Filter, Show Details, Edit Details (with delete), Add Data, Add Navigation (shell plus second view), Deep Link, Test the View, Wrap Up (with the finished repository and the login exercise pointing at Next Steps).
docs: resolve stale TODOs and work-in-progress notes in Building Apps…
docs: add a Building Apps guide on application-wide error handling (#…
docs: add Building Apps landing page intros, expand Strong Consistenc…
peholmst commentedon Oct 10, 2026
Defect issues
@EnableMethodSecurityis now required and shown in the React guide, with a caution box; the REST@Ordersentence now says "a lower@Ordervalue"; the logout success URL is permitted explicitly and the logout view no longer sits on/logout; React/Flow opposite defaults have a side-by-side box.@TransactionalEventListenerin Add a Service, Event-Triggered Jobs, and a rewritten Eventual Consistency;@Transactionaladded to the service examples; the "repository from the UI" sidebars replaced by a Calling Repositories from Views section with four explicit conditions; startup trigger usesApplicationRunner;saveAndFlushexplained.subscribe(onNext, onError), the virtual-thread and executor examples do the work outsideUI.access(), route template fixes, swapped React callouts, Wikipedia link, "LM Studio". The custom-field page shrank by about 1,000 lines and its examples are compiled.// TODOcomments, and zero front-matter-only landing pages remain in the two sections. All seven landing pages have an intro and a reading order. Strong and Eventual Consistency are real pages.react/; Lumo tokens remain only where flagged.jakarta.servlet6.1, and runs Gretty 5 with Jetty 12 or Tomcat 11. #6365 did the same for the Hilla Gradle reference.The seven findings of this issue
UI.access(), and thread-local state including theSecurityContext; how browser and server stay in sync, what happens when the connection is lost, and resynchronization (which reruns detach and attach listeners); deployment consequences; and a Flow/React comparison with the opposite access defaults and guidance on choosing, including team skills. Linked from the Getting Started index, the quick start, Next Steps, the Building Apps and Architecture indexes, Layers, Monoliths, and React Views. The server-push Threads page gained Calling Protected Services (DelegatingSecurityContextRunnable).@Scheduledjobs run on every instance.$badge and the Commercial Feature notice). It also covers what a license means for developer machines, CI, and production, and the release and free-maintenance model. The page names no commercial products or subscription tiers, because licensing changes; vaadin.com/pricing is the source of truth. Linked from the Getting Started index, Next Steps (new Plan for Licensing & Upgrades section), the Building Apps and Architecture indexes, and the runtime model. Supported Technologies is now linked from the Getting Started index, Development Environment, Next Steps, and Project Structure, and the Upgrading Guide from Next Steps. Copilot, free since 25.1, lost its stale commercial markers on the Tools card and the Licenses page.Additional gaps listed in the issue
Tutorial steps (second comment)
@Transactionalrollback, three browserless view tests that find components the way a user does, and a "make it fail" exercise for both.@Route("")and no layout, menu, or second view.What remains, in priority order
@Schedulednote to Background Jobs.Acceptance criteria
docs: explain the runtime model of a Vaadin application (#6368)
docs: map free and commercial features, support, and maintenance (#6370)
docs: require Spring Boot 4.1 in the upgrading guide (#6371)
docs: show how to measure capacity and test failover (#6381)
docs: add navigation and delete steps to the tutorial (#6380)
docs: warn against measuring sessions by their retained size (#6392)
docs: add production how-to guides to Building Apps (#6382)
docs: explain when to use Vaadin, and when not to