Documentation

Documentation versions (currently viewingVaadin 24.4 (pre))

Using Quarkus with Vaadin

How to use Quarkus with Vaadin.

Quarkus is an open source, Kubernetes-native Java framework made for Java virtual machines and native compilation. It optimizes Java specifically for containers, enabling it to become an effective platform for serverless, cloud, and Kubernetes environments.

For more information on Quarkus, see the Quarkus site.

Starting a Project

To start a new project with Quarkus and Vaadin, you can download the Quarkus base starter. It’s a project template with the necessary configuration and dependencies for building an application.

It’s also available with Gradle configuration in the Gradle branch on GitHub.

Manual Setup

To be able to run an existing project with Quarkus, you’ll need to have the vaadin-quarkus and vaadin-jandex Maven dependencies in the project, as well configure the quarkus-maven-plugin.

Below is an example of how that might be done:

<dependencyManagement>
    <dependencies>
        <!-- Quarkus Platform BOM to keep the project
             artifacts in synch with the quarkus.version -->
        <dependency>
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <!-- Vaadin Platform BOM -->
        <dependency>
            <groupId>com.vaadin</groupId>
            <artifactId>vaadin-bom</artifactId>
            <type>pom</type>
            <scope>import</scope>
            <version>${vaadin.version}</version>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- The Vaadin Quarkus extension -->
    <dependency>
        <groupId>com.vaadin</groupId>
        <artifactId>vaadin-quarkus-extension</artifactId>
        <version>${vaadin.version}</version>
    </dependency>

    <!-- The jandex.idx for Vaadin-core annotation indexes
         automatically included via vaadin-quarkus-extension
         and is used as an offline reflection library.

         If you want to work with Pro components such GridPro,
         you can uncomment the following dependency to include the
         officially provided jandex.idx for them as well: -->
    <!--
    <dependency>
        <groupId>com.vaadin</groupId>
        <artifactId>vaadin-jandex</artifactId>
    </dependency>
    -->

    <!-- Quarkus always pulls in slf4j-jboss-logmanager
         into target/lib; don't use slf4j-simple -->
    <dependency>
        <groupId>org.jboss.slf4j</groupId>
        <artifactId>slf4j-jboss-logmanager</artifactId>
        <version>1.1.0.Final</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <!-- For in-depth information on quarkus-maven-plugin
             see https://quarkus.io/guides/maven-tooling#build-tool-maven -->
        <plugin>
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-maven-plugin</artifactId>
            <version>${quarkus.version}</version>
            <extensions>true</extensions>
            <executions>
                <execution>
                    <goals>
                        <!-- Builds the Quarkus application -->
                        <goal>build</goal>
                        <!-- in these goals the Quarkus application bootstrap
                             is initialized and re-used in the build goal -->
                        <goal>generate-code</goal>
                        <goal>generate-code-tests</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Vaadin CDI Features

Since Quarkus’s dependency injection solution is based on CDI, it’s possible to use all CDI features.

See these documentation pages for Vaadin CDI features:

Vaadin Add-Ons in Quarkus

Any Vaadin add-on used in a Quarkus application should contain a Jandex index. You can generate this using the jandex-maven-plugin. See How to Generate a Jandex Index.

If you can’t modify the dependency, you can still have Quarkus index it by adding quarkus.index-dependency entries to your application.properties:

quarkus.index-dependency.<name>.group-id=
quarkus.index-dependency.<name>.artifact-id=
quarkus.index-dependency.<name>.classifier=(this one is optional)

The <name> string here is used to link the group-id, artifact-id and classifier entries in one logical block. It should be the same for these three entries, and be any string literal.

Development Mode

After doing the Manual Setup, the Quarkus application can be started in development mode using the quarkus:dev goal in Maven:

mvn package quarkus:dev

The application is then available at localhost:8080 in the browser.

Production Mode

The Quarkus base starter already includes the necessary Maven configuration to run the application in production mode. If you have a project not based on the starter, it’ll need the configuration described in Deploying to Production.

When you’re ready, run the following commands to start the application:

mvn package -Pproduction
java -jar target/quarkus-app/quarkus-run.jar

Live Reload

Live reload functionality is supported for changes in either Java or frontend files.

When running in development mode (i.e., quarkus:dev), changes in Java or frontend files compile after saving and appear after the browser page is refreshed. For frontend changes, the browser page is automatically reloaded. However, for Java changes a manual refresh is required. Furthermore, Java hot reload may sometimes break frontend live reload. If this happens, the server needs to be restarted.

Integrating Vaadin With an Existing Quarkus Application

One of the things to consider when integrating Vaadin with an existing Quarkus application is that the application may already have set up routes that may effectively "shadow" the Vaadin UI. A typical scenario for adding Vaadin to an existing Quarkus application is providing some sort of administration dashboard functionality that sits under a sub-root path, e.g., /admin. Going with the documented way of setting a @Route at the view level, won’t solve the issue:

// This won't solve the issue
@Route("/admin")
public class MainView extends VerticalLayout {

The problem is that by default, Vaadin’s Quarkus extension would spin a QuarkusVaadinServlet instance that expects every call to the root (/) of your Quarkus app to go through it. If there is even a single @Path("/") annotation anywhere in the app’s code, it may effectively "shadow" the access to the servlet.

To solve that, you need to either remove the @Path("/") annotations if possible (may be impossible if those serve the index page of your site alredy, for instance), or create a custom instance of QuarkusVaadinServlet that would take place instead of the default one:

@WebServlet(urlPatterns = "/admin/*", name = "AdminServlet", asyncSupported = true)
public class AdminServlet extends QuarkusVaadinServlet {

See how the servlet listens to incoming requests matching the /admin/* mapping and not the root anymore. In this case, you also need to adjust Vaadin’s @Route annotations accordingly. For example, @Route("/admin") would now simply turn into @Route(""), otherwise, your view would expect to be called with /admin/admin, which is likely not what you desire.

Limitations

The Vaadin Quarkus add-on doesn’t support Hilla because Hilla requires the use of Spring. Adding the Quarkus Spring extensions doesn’t allow Hilla to work correctly because the extensions don’t provide a complete Spring implementation. This is explained in the Important Technical Note paragraph of the Quarkus Spring DI documentation.

Known Issues

Quarkus Bill-of-Materials (BOM) may pin libraries to a version that conflicts with Vaadin. This can result in runtime or test failures during development because of changes in method signatures.

For example, one common problem is a conflict with the Java Native Access (JNA) version. That may cause runtime errors such as java.lang.NoClassDefFoundError: com/sun/jna/platform/unix/LibCAPI$size_t$ByReference or java.lang.NoSuchMethodError: 'void com.sun.jna.Memory.close()', depending on the platform the application is running.

This can be fixed by making sure the Vaadin BOM in the dependency management section of the project’s pom.xml file is located immediately above the reference to Quarkus BOM.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.vaadin</groupId>
            <artifactId>vaadin-bom</artifactId>
            <type>pom</type>
            <scope>import</scope>
            <version>${vaadin.version}</version>
        </dependency>
        <dependency>
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        ...
    </dependencies>
</dependencyManagement>

45A37C7E-2C03-44CA-B59E-C756F05CE3D2