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-hillaforLitbased applicationsquarkus-hilla-reactforReactbased 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.
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.
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.
The current Hilla support has some known limitations:
- Stateless Authentication is not supported
- Native image compilation does not work
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.
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.
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.
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.5.x</version>
</dependency>or
<dependency>
<groupId>com.github.mcollovati</groupId>
<artifactId>quarkus-hilla-react</artifactId>
<version>24.5.x</version>
</dependency>| Quarkus-Hilla / Hilla | Quarkus | Vaadin |
|---|---|---|
|
 |
 |
 |
 |
 |
 |
 |
 |
 |
|
|
 |
|
|
 |
|
 |
 |
 |
 |
|
 |
 |
NOTE: The major and minor version of Quarkus-Hilla always matches the Vaadin/Hilla version.
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
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
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
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!