Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mcollovati/quarkus-hilla

A Quarkus extension to run Hilla applications on Quarkus.
https://github.com/mcollovati/quarkus-hilla

hilla quarkus quarkus-extension

Last synced: 3 months ago
JSON representation

A Quarkus extension to run Hilla applications on Quarkus.

Host: GitHub
URL: https://github.com/mcollovati/quarkus-hilla
Owner: mcollovati
License: apache-2.0
Created: 2023-02-14T16:38:37.000Z (almost 2 years ago)
Default Branch: main
Last Pushed: 2024-10-27T07:48:59.000Z (3 months ago)
Last Synced: 2024-10-27T20:06:09.609Z (3 months ago)
Topics: hilla, quarkus, quarkus-extension
Language: Java
Homepage:
Size: 9.12 MB
Stars: 14
Watchers: 4
Forks: 0
Open Issues: 20
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

![quarkus-hilla-banner.svg](etc/quarkus-hilla-banner.svg)

# Quarkus - Hilla

[![Maven Central 24.x](https://img.shields.io/maven-central/v/com.github.mcollovati/quarkus-hilla?style=for-the-badge&logo=apache-maven&versionPrefix=24.)](https://central.sonatype.com/artifact/com.github.mcollovati/quarkus-hilla)
[![Maven Central 24.4](https://img.shields.io/maven-central/v/com.github.mcollovati/quarkus-hilla?style=for-the-badge&logo=apache-maven&versionPrefix=24.4)](https://central.sonatype.com/artifact/com.github.mcollovati/quarkus-hilla)
[![Maven Central 2.x](https://img.shields.io/maven-central/v/com.github.mcollovati/quarkus-hilla?style=for-the-badge&logo=apache-maven&versionPrefix=2.)](https://central.sonatype.com/artifact/com.github.mcollovati/quarkus-hilla)
[![Maven Central 1.x](https://img.shields.io/maven-central/v/com.github.mcollovati/quarkus-hilla?style=for-the-badge&logo=apache-maven&versionPrefix=1)](https://central.sonatype.com/artifact/com.github.mcollovati/quarkus-hilla)
[![Apache License 2.0](https://img.shields.io/github/license/mcollovati/quarkus-hilla?style=for-the-badge&logo=apache)](https://www.apache.org/licenses/LICENSE-2.0)

A [Quarkus](https://quarkus.io) extension to run [Hilla](https://hilla.dev)
applications on Quarkus.

Hilla is an open source framework, provided by [Vaadin Ltd.](https://vaadin.com),
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](https://hilla.dev/docs/lit/guides/endpoints),
[Reactive Endpoints](https://hilla.dev/docs/lit/guides/reactive-endpoints)
and [Security](https://hilla.dev/docs/lit/guides/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](https://github.com/vaadin/quarkus/), 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.

## Limitations

The current Hilla support has some known limitations:

* The endpoint prefix is not configurable
* [Stateless Authentication](https://hilla.dev/docs/lit/guides/security/spring-stateless)
is not supported
* Native image compilation does not work

## Auto CRUD, Auto Grid and Auto Form

Support
for [Auto CRUD](https://hilla.dev/docs/react/components/auto-crud), [Auto Grid](https://hilla.dev/docs/react/components/auto-grid[)
and [Auto Form](https://hilla.dev/docs/react/components/auto-crud) 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](https://github.com/mcollovati/quarkus-hilla/wiki/Crud-List-repository-service) 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](https://github.com/vaadin/hilla/issues/211),
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](https://github.com/vaadin/vaadin-usage-statistics#opting-out).

## Getting started

Get started with `quarkus-hilla` by following the [Quick Start Guide](../../wiki/QuickStart)
or download the [starter project](https://github.com/mcollovati/quarkus-hilla-starter).

```xml

com.github.mcollovati
quarkus-hilla
24.4.x

```

```xml

com.github.mcollovati
quarkus-hilla-react
24.4.x

```

## 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:

```terminal
mvn -DskipTests install
```

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

```terminal
mvn -DtrimStackTrace=false verify
```

End-to-end test modules can be found in the `integration-tests` folder.
Integration tests use [Selenide](https://selenide.org/) 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.

```terminal
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`.

```terminal
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.

```terminal
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.

```terminal
mvn -Pupdate-hilla-codestart
```

## Release

The release process is based on the awesome [JReleaser](https://jreleaser.org/) 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.

```terminal
mvn clean
mvn -Pdistribution -Drevision= -DskipTests -DaltDeploymentRepository=local::file:./target/staging-deploy deploy
mvn -N -Pdistribution -Drevision= jreleaser:full-release
```

## Contributors ✨

Thanks goes to these wonderful
people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

_{Marco Collovati}
💻 🚧

_{Dario Götze}
💻 🚧

This project follows
the [all-contributors](https://github.com/all-contributors/all-contributors)
specification. Contributions of any kind are welcome!