Oft sieht man in den READMEs populärer Open-Source-Projekte eine Vielzahl bunter Badges, die einem eine schnelle Übersicht über den Projektstatus geben sollen. Für öffentliche Projekte gibt es bereits Services wie Shields.io, doch wie kann man Badges für private/unternehmensinterne Projekte erstellen? In diesem Artikel wollen wir uns anschauen, wie auch wir eigene Badges erstellen und diese dann in unseren Projekten einbinden können.
Der fertige Code kann hier gefunden werden.
Ausgangssituation
Wir entwickeln eine versionierte Webseite, deren Quellcode auf einem unternehmensinternen Server liegt (z.B. GitLab). Die Abhängigkeiten unserer Webseite managen wir mit npm.
Badges erstellen
Natürlich sind uns keine Grenzen gesetzt, welchen Inhalt unsere Badges haben werden. Doch für einen leichten Einstieg demonstriere ich, wie wir ein Badge erstellen können, welches die aktuelle Version unseres Projekts darstellt.
Die Version anhand der package.json herausfinden
Wenn wir die Version unserer Webseite in der package.json pflegen, ist es ein Leichtes, diese programmatisch zu extrahieren:
Führen wir dieses Skript via node scripts/badges.js aus, wird das Attribut version aus der package.json geladen und schließlich in der Konsole ausgegeben.
Das Skript erweitern
Um ein Badge zu erstellen, wird das Paket badge-maker benötigt:
Um dieses Paket im Code zu verwenden, muss es vorerst in unserem Skript importiert werden.
Außerdem benötigen wir das Modul fs, welches in Node.js integriert ist und deshalb nicht extra installiert werden muss:
fsermöglicht Interaktionen mit dem Dateisystem und wird spätestens benötigt, sobald wir das Badge in einer Datei speichern wollen.
Nun können wir aus der extrahierten Version ein Badge erstellen:
Die Funktion makeBadge() liefert einen String mit dem Badge im SVG-Format. Ihr muss ein Objekt übergeben werden, in dem das Format des Badges beschrieben wird (siehe https://www.npmjs.com/package/badge-maker#format).
In unserem Beispiel erhalten wir folgendes Badge:
Gespeichert werden sollen unsere Badges im Verzeichnis badges/, welches zunächst erstellt werden muss:
fs.mkdir() erwartet eine Callback-Funktion, der bei einem Fehler eben dieser übergeben wird. Da diese Funktion jedoch bei jedem Aufruf ausgeführt wird, sollte man überprüfen, ob es überhaupt einen Fehler gibt. Außerdem wollen wir keinen Fehler ausgeben, wenn das Verzeichnis bereits existiert (der Fehlercode dafür ist -17).
Zu guter Letzt speichern wir das Badge in badges/version.svg:
Vereinen wir nun diese Codeschnipsel in einem Skript und führen dieses via node scripts/badges.js aus, finden wir anschließend ein neues Verzeichnis, badges/, welches die Datei version.svg beinhaltet.
Das Badge in der README einbinden
Schließlich müssen wir das jüngst erstellte Badge ./badges/version.svg nur noch in der README einbinden:
Standardmäßig würde man zur Datei des Badges gelangen, wenn man auf diese klickt. Um dies zu verhindern, kann sie auf etwas verlinken:[](https://example.com "Tooltip, der beim Hovern angezeigt wird").
Das Erstellen der Badges automatisieren
Damit wir die Badges nicht jedes Mal manuell aktualisieren müssen, können wir deren Erstellung automatisieren. Dazu erweitern wir die package.json um folgende Skripte:
Nun werden die Badges jedes Mal neu erstellt, nachdem npm install ausgeführt wurde.
Voraussetzung hierfür ist, dass es einen anderen Automatismus gibt, der z.B. bei jedem Push auf den Server einnpm installausführt. Beispielsweise könnte man bei einem GitLab-Projekt die CI-Pipeline um einen Job erweitern, dernpm installimmer dann ausführt, wenn es Änderungen an derpackage.jsongab. Je nach Inhalt des Badges kann es natürlich sinnigere Trigger geben.
Noch mehr Badges!
Anzahl veralteter Abhängigkeiten
Folgendes Badge zeigt an, wie viele Abhängigkeiten veraltet sind. Dies ist hilfreich, um immer auf dem neusten Stand zu bleiben. Um diese Anzahl herauszufinden, kann das Paket npm-check verwendet werden:
Version einer Abhängigkeit
Um die Version einer einzelnen Abhängigkeit anzuzeigen, kann wie bei der Version des Projekts wieder auf die package.json zugegriffen werden. Dies sollte nur für elementare Abhängigkeiten geschehen (z.B. nur für angular in einem Angular-Projekt).
Letzte Modifizierung am Projekt
Um das Datum der letzten Modifizierung anzuzeigen, kann folgender Ausdruck verwendet werden. Dies ist hilfreich um in Erfahrung zu bringen, wann zuletzt am Projekt gearbeitet wurde.
Fazit: Einfacher als gedacht!
In diesem Beitrag wurde gezeigt, wie Badges für ein Projekt mithilfe von badge-maker (https://www.npmjs.com/package/badge-maker) erstellt werden können. Diese Badges können nützliche Informationen auf einen Blick liefern, wie zum Beispiel die aktuelle Version des Projektes. Dabei ist nicht relevant, ob das Projekt nur privat, auf einem eigenen Server, oder öffentlich verfügbar ist. Uns sind bei der Erstellung also keine Grenzen gesetzt!
Weiterführende Links
badge-makerauf npmjs.com- GitLab CI/CD
- GitHub Actions
npm-checkauf npmjs.com- Array.filter()
- Reguläre Ausdrücke