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.

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

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.

Limitations

The current Hilla support has some known limitations:

The endpoint prefix is not configurable
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.

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.4.x</version>
</dependency>

<dependency>
    <groupId>com.github.mcollovati</groupId>
    <artifactId>quarkus-hilla-react</artifactId>
    <version>24.4.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

Development 24.5-SNAPSHOT Quarkus 3.12+ Vaadin 24.5

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!

mcollovati/quarkus-hilla