Einleitung

Es ist ein gängiges Muster, Anwendungsinformationen im Frontend einer Webanwendung anzuzeigen. Neben dem Namen der Anwendung wird in der Regel auch die Version der Anwendung angezeigt. Diese Art von Informationen sind nützlich, um Endanwender:innen zu unterstützen, wenn sie auf Probleme oder Fehler in der Anwendung stoßen. Sie können sich an das Support-Team wenden und ihnen mitteilen, in welcher Version der Anwendung ein Problem aufgetreten ist. Ein weiterer nützlicher Anwendungsfall ist die kontinuierliche Bereitstellung und Prüfung einer Webanwendung. Jedes Mal, wenn eine neue Funktion integriert oder ein Fehler behoben wurde, sollte eine neue Version der Anwendung erstellt und in einer Test- oder QA-Umgebung bereitgestellt werden, um Tester:innen oder Endanwender:innen die Möglichkeit zu geben, die Version zu überprüfen. In diesem Fall ist es wichtig, dass die Benutzer:innen erkennen können, mit welcher App-Version sie gerade arbeiten.

Grundlagen

Wie kann man also diese Art von Anwendungsinformationen im Frontend einer Hilla-App anzeigen? Zu Beginn muss man sicherstellen, dass irgendeine Art von Anwendungsversionierung vorhanden ist. Egal, ob man die Patch-, Minor- oder Major-Versionen der Anwendung manuell hoch zählt oder ob man ein vorhandenes Tool oder Plugin wie das Nebula Release Plugin von Netflix verwendet. Man sollte eine Möglichkeit vorsehen, die Version der Anwendung anzugeben, und idealerweise muss man die Version nur an einer Stelle angeben und aktualisieren, um nur eine Single Source of Truth zu haben. Ich bevorzuge es, die Versionierung im Spring Boot Backend der Hilla-Anwendung durchzuführen.

Versionierung einrichten

In einem aktuellen Projekt habe ich die Versionierung im Spring Boot Backend einer Hilla-App mit Hilfe des Netflix Nebula Release Plugins und Gradle eingerichtet. Die Installation und Einrichtung des Netflix Nebula Release Plugin ist nicht im Scope dieses Artikels. Man findet eine umfangreiche Dokumentation zu Netflix Nebula im Allgemeinen unter https://nebula-plugins.github.io/. Informationen zum Netflix Nebula Release Plugin findet man im offiziellen GitHub-Repository unter https://github.com/nebula-plugins/nebula-release-plugin.

Hat man das Nebula Release Plugin eingerichtet, wird es während des Build-Prozesses der Hilla-App die nächste Versionsnummer der Anwendung auf Grundlage der vorhanden Informationen und Konfiguration ermitteln. Die ermittelte Version steht anschließend im Gradle project Objekt project.version zur Verfügung. Der Name der Anwendung kann ebenfalls in diesem Objekt abgelegt werden. So kann man beispielsweise project.name setzen, wenn man zunächst einen neuen Eintrag in der Datei gradle.properties ergänzt:

projectName=my-app

Anschließend kann man diese Property dann in der Datei settings.gradle wie folgt verwenden:

rootProject.name = "${projectName}"

Die Version und der Name der Anwendung im project Objekt können nun in weiteren Schritten im Build-Prozess der Anwendung genutzt werden.

Anwendungsinformationen in das Frontend bringen

Eine Möglichkeit besteht in der Nutzung des Tasks processResources. In der Datei build.gradle des Hilla-Projektes kann dafür der folgende Abschnitt ergänzt werden:

processResources {
    filesMatching("vite.env") {
       expand(["projectName": project.name, "projectVersion": project.version])
       copyTo("./src/main/frontend/.env" as File)
    }
}

Dieser Task sucht nach einer passenden Datei vite.env im Verzeichnis src/main/resources. Diese Datei hat den folgenden Inhalt:

VITE_APP_NAME=${projectName}
VITE_APP_VERSION=${projectVersion}

Die Platzhalter ${projectName} und ${projectVersion} werden mit den passenden Werten aus dem Gradle project Objekt ersetzt, so wie zuvor beschrieben.

Anschließend wird die verarbeitete Datei nach src/main/frontend/.env kopiert und hat dann beispielsweise diesen Inhalt:

VITE_APP_NAME=my-app
VITE_APP_VERSION=0.16.0

Anwendungsinformationen im Frontend anzeigen

Vite behandelt die Datei src/main/frontend/.env als eine Quelle für Umgebungsvariablen. Standardmäßig werden nur Variablen mit dem Präfix VITE_ verarbeitet und verfügbar gemacht. Die verfügbaren Umgebungsvariablen können nun im Frontend-Code der Hilla-App verwendet werden. Zum Beispiel in src/main/frontend/views/@layout.tsx, um die Anwendungsinformationen im Menü anzuzeigen:

<span className={'text-s'}>
  {import.meta.env.VITE_APP_NAME} ({import.meta.env.VITE_APP_VERSION})
</span>

Die Verarbeitung und Verfügbarkeit von Umgebungsvariablen in Vite kann vielfältig angepasst werden. Weitere Informationen dazu finden sich in der offiziellen Dokumentation: https://vite.dev/guide/env-and-mode.

Fazit

Anwendungsinformationen im Frontend einer Hilla-App anzuzeigen ist ein nützliches Muster. Durch die Kombination von Gradle, dem Nebula Release Plugin von Netflix und Umgebungsvariablen in Vite kann dieses Muster einfach implementiert werden.

Bildnachweis:

Cover-Bild Quelle: https://www.flickr.com/photos/snapsi42/3344629933/in/album-72157614968950745
Cover-Bild Lizenz: https://creativecommons.org/licenses/by-nc-nd/2.0/

Wie kann man Anwendungsinformationen in Hilla anzeigen?