Quarkus - Hilla

A Quarkus extension to run Hilla applications on Quarkus.

Hilla is an open source framework, provided by Vaadin Ltd., that integrates a Spring Boot Java backend with a reactive TypeScript frontend.

This extension replaces the Spring Boot backend with Quarkus Context & Dependency Injection (CDI) and RESTEasy Reactive for a simpler integration with Quarkus, but preserves the main features of the Hilla Framework, such as Endpoints, Reactive Endpoints and Security.

NOTE: This is an unofficial community extension, and it is not directly related nor supported by Vaadin Ltd.

Notable changes

Lit and React extensions

Starting with 2.4.1, the extension is subdivided into two main artifacts based on the desired front-end framework:

• quarkus-hilla for Lit based applications
• quarkus-hilla-react for React based applications

Vaadin Unified platform

Since Vaadin 24.4, Flow and Hilla are unified in a single platform. As a consequence, there have been a considerable amount of changes in Hilla, for example the groupId of Maven artifacts and Java package names moved from dev.hilla to com.vaadin.hilla. Quarkus-Hilla will follow the Vaadin platform releases, so the extension version will bump from 2.5 series to 24.4. In addition, the minimum supported Quarkus version will be 3.7.

Integration with Vaadin Quarkus extension

To provide better support for Hilla on the Quarkus platform and simplify maintenance, the quarkus-hilla extension will depend on the existing Vaadin Quarkus extension, starting with 24.5. This integration eliminates the need for code duplication and ensures tighter alignment with Vaadin's ecosystem, offering more streamlined updates and improved stability. By leveraging the Vaadin Quarkus extension, users of quarkus-hilla will benefit from enhanced compatibility with future Vaadin features.

Custom Endpoint Prefix

A custom endpoint prefix can be configured by setting the vaadin.endpoint.prefix entry in application.properties. The extension will create a custom connect-client.ts file in the frontend folder and construct the ConnectClient object with the configured prefix. If connect-client.ts exists and does not match the default Hilla template, it is not overwritten.

Limitations

The current Hilla support has some known limitations:

• Stateless Authentication is not supported
• Native image compilation does not work

Auto CRUD, Auto Grid and Auto Form

Support for Auto CRUD, Auto Grid and Auto Form is available in quarkus-hilla-react. However, both extensions provides custom implementations of CrudRepositoryService and ListRepositoryService, based on quarkus-spring-data-jpa or quarkus-hibernate-orm-panache extension. See the documentation for additional details.

Endpoints live reload

In dev mode, Quarkus uses a ClassLoader hierarchy that enables the live reload of user code without requiring a rebuild and restart of the application. However, the reload is usually triggered by a HTTP request, for example a browser page reload. To simplify development, quarkus-hilla extends Quarkus Live Reload feature to re-generated client side code upon changes on Hilla endpoint related classes. To trigger live reload, the extension scans for file changes either in source code or compiled classes folders (e.g. src/main/java or target/classes in a Maven project). The default strategy is to watch for class files, but it can be changed with the vaadin.hilla.live-reload.watch-strategy property. Endpoints live reload is disabled by default, but can be activated setting the vaadin.hilla.live-reload.enable property to true in the application.properties file. To prevent excessive reloads, the watched folders can be restricted by providing a list of relative paths with the vaadin.hilla.live-reload.watched-paths property. The Endpoints live reload feature works better if quarkus.live-reload.instrumentation is set to true, since this setting allows Quarkus to potentially redefine classes at runtime without triggering a server restart.

Below, there's an example configuration, for an application that stored Hilla related classes in src/main/java/com/example/ui folder.

quarkus.live-reload.instrumentation=true
vaadin.hilla.live-reload.enable=true
vaadin.hilla.live-reload.watch-strategy=source
vaadin.hilla.live-reload.watched-paths=com/example/ui

NOTE: currently source file watch strategy supports only Java file, not Kotlin. This is because the watcher inspects the source code to detect all declared type, but the parser currently works only for Java source files.

Usage statistics

As discussed in this Hilla ticket, the extension report itself to the Vaadin usage statistics mechanism in order to get a better understanding of how widely the extension is used compared to Hilla usage in general. The hope is that, based on this data, Vaadin may consider in the future to provide an official extension. Statistic are collected only in development mode and no sensitive data is gathered. For instructions on how to opt-out, see the client-side collector repository.

Getting started

Get started with quarkus-hilla by following the Quick Start Guide or download the starter project.

<dependency>
    <groupId>com.github.mcollovati</groupId>
    <artifactId>quarkus-hilla</artifactId>
    <version>24.6.x</version>
</dependency>

or

<dependency>
    <groupId>com.github.mcollovati</groupId>
    <artifactId>quarkus-hilla-react</artifactId>
    <version>24.6.x</version>
</dependency>

Releases

Quarkus-Hilla / Hilla	Quarkus	Vaadin

NOTE: The major and minor version of Quarkus-Hilla always matches the Vaadin/Hilla version.

Development

Build and test

To build the extension locally you need to install JDK 17 or later and Maven 3.8 or later.

The extension and its required dependencies can be built by typing the following command:

mvn -DskipTests install

To run the test suite, execute the maven verify goal:

mvn -DtrimStackTrace=false verify

End-to-end test modules can be found in the integration-tests folder. Integration tests use Selenide for browser interaction, the browser used by default is Chrome, except for MacOS, where Safari is used. Execution of end-to-end integration tests requires the activation of the maven it-tests profile.

mvn -DtrimStackTrace=false -Pit-tests verify

The same tests can also be executed in production mode, by activating the production profile in addition to it-tests.

mvn -DtrimStackTrace=false -Pit-tests,production verify

Tests run by default in headless mode, meaning that the browser window will not be visible during the execution, unless a debugger is attached to the JVM, either by running the tests in debug mode from the IDE, or by providing the -Dmaven.surefire.debug system property to the maven command line.

mvn -DtrimStackTrace=false -Dmaven.surefire.debug -Pit-tests verify

Update codestarts

The source code of the extension codestarts are built, using the Hilla application scaffold utility (HillaAppInitUtility). To update the source code, run the following command in the runtime and runtime-react folders, and commit the changes.

mvn -Pupdate-hilla-codestart

Release

The release process is based on the awesome JReleaser tool.

To perform a manual release type the following commands. Version must be in format N.N.N, for example 1.0.0. Pre-releases can use -alpha, -beta and -rc suffix, followed by a number, for example 1.0.0-beta2.

Environment variables required by the release process:

• JRELEASER_GITHUB_TOKEN: to create release on GitHub
• JRELEASER_GPG_PUBLIC_KEY, JRELEASER_GPG_SECRET_KEY and JRELEASER_GPG_PASSPHRASE: to sign artifacts
• JRELEASER_NEXUS2_MAVEN_CENTRAL_USERNAME and JRELEASER_NEXUS2_MAVEN_CENTRAL_PASSWORD: to publish on maven central

Use -Djreleaser.dry.run=true flag to test the release without publishing artifacts.

mvn clean
mvn -Pdistribution -Drevision=<version-to-release> -DskipTests -DaltDeploymentRepository=local::file:./target/staging-deploy deploy
mvn -N -Pdistribution -Drevision=<version-to-release> jreleaser:full-release

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Marco Collovati 💻 🚧

Dario Götze 💻 🚧

This project follows the all-contributors specification. Contributions of any kind are welcome!