Docs

Docs

Architecture Overview

The parts of an application with a Vaadin UI, where each one runs, how they communicate, and how a UI component works.

An application with a Vaadin UI is a Java application with a web user interface. Some parts of it run in the browser, some on the server, and one part is produced when you build the application. You build the user interface from views. Typically, most of them are Java views, which run on the server. You can also add React views, which run in the browser. The following diagram shows all the parts, and how they communicate:

A diagram of a Vaadin application: the Vaadin client engine

The green boxes are the code of your own application project: your views and your application services. The blue boxes are provided by Vaadin, and you don’t write code for them: the Vaadin components and the Vaadin client engine, with the VaadinSession and UI objects drawn as light blue frames around your Java view. The orange boxes are the build tools: the Vaadin Maven or Gradle plugin, and the frontend bundle that it produces. Conceptual Layers explains why the UI layer of a view that runs on the server spans both the browser and the server.

In the Browser

In the browser, a Vaadin component is a web component, such as <vaadin-button> or <vaadin-grid>. Vaadin views use them to build the page that the user sees.

The Vaadin client engine is the part of Vaadin that runs in the browser on behalf of your Java views. It updates the page — the Vaadin components and any other HTML elements — as the server tells it to, and sends the user’s events, such as clicks and changed field values, to the server. You don’t write code for it.

React views are optional. If you write some views in React and TypeScript, they run entirely in the browser and use the same Vaadin components through their React wrappers. See React Views for when they’re a better fit than Java views.

On the Server

The server runs your application in a JVM, for example as a Spring Boot application. Vaadin also works with Quarkus, Jakarta EE servers, and plain servlet containers.

For each user and browser, the server keeps a VaadinSession, which is tied to the HTTP session. It holds one UI for every browser tab that the user has open. The UI holds the Java view that the tab shows, as a tree of Java objects for the UI components on the page. This is where your Java views run. See Views & Navigation for how to create them.

Application services are your business logic: ordinary Java classes, typically Spring beans, together with the repositories and other code behind them. They’re shared by all users, and they talk to the database and to other systems.

How Views Reach Your Services

Java views and React views reach your application services in different ways:

  • A Java view runs on the server, so it calls an application service directly, as an ordinary Java method call. The Vaadin client engine and the server keep the page and the Java objects in sync by exchanging JSON messages: events go to the server, and the resulting changes to the UI come back. How Vaadin Works at Runtime follows a single click through this cycle, and explains what it means for latency, threading, and deployment.

  • A React view runs in the browser, so it calls a service over HTTP. You annotate the service with @BrowserCallable, and Vaadin generates a TypeScript client for it. See Call Java Services from React Views.

Either way, you don’t need to design a REST API for your own user interface.

At Build Time

The JavaScript and CSS that the browser needs — the Vaadin components, the Vaadin client engine, your React views, and your styles — are packaged into a frontend bundle. The browser loads it when it opens the application. In a production build, the Vaadin Maven or Gradle plugin creates the bundle with Vite, or uses a pre-compiled bundle when the application doesn’t need one of its own. Production Build describes when each one is used, and Development Mode describes how the frontend is served during development.

How a UI Component Works

A Vaadin component, such as a button, has two halves: a web component that the browser renders, and, for Java views, a Java class that you use on the server. The following diagram shows them for a button:

A diagram of a Vaadin button: the vaadin-button web component

  • The web component is a custom HTML element, such as <vaadin-button>. Its JavaScript comes from an npm package, and is part of the frontend bundle. The web component renders itself, and reacts to user input such as typing or hovering in the browser, without a round trip.

  • The Java component, such as Button, is what a Java view uses. Its API — setText(), addClickListener(), and so on — changes the element in the browser and listens to its events.

  • The Vaadin client engine keeps each Java component in sync with its web component in the browser. It applies the changes made on the server, and sends back the events that the server listens to.

  • Annotations on the Java class connect the two halves: @Tag names the HTML element, and @NpmPackage and @JsModule tell the build which JavaScript the component needs.

  • A React view uses the same web component through a React wrapper, such as <Button> from @vaadin/react-components. It doesn’t involve the Java component or the Vaadin client engine.

Compose with Components shows how to use the Java components in a view. You can also build components of your own in the same way. See Components for how-to guides, such as wrapping an existing web component, and the Component Internals reference for the details.

Where to Go Next