Zum Hauptinhalt springen

Erstellen, Hosten und Verteilen von gemeinsam genutzten Paketen

Note: Diese Funktion der Jutro Web Apps wird in Kürze verfügbar sein. Der Release erfolgt schrittweise. Wenden Sie sich bitte an Ihren Guidewire-Vertreter, um Zugang zu erhalten.

In diesem Abschnitt erfahren Sie mehr über gemeinsam genutzte Paketquellen – wie Sie sie erstellen, wo Sie sie aufbewahren und wofür Sie sie verwenden können.

Neben der Bereitstellung von Repositorys für Ihre Jutro-Apps bietet die Jutro Digital Platform jetzt auch ein Repository für die Erstellung gemeinsam genutzter Pakete.

Gemeinsam genutzte Pakete sind eine Möglichkeit, Code und Funktionen in mehreren Jutro-Apps gemeinsam zu nutzen. Sie sind eine großartige Möglichkeit, Code und Funktionen wiederzuverwenden und Ihre Apps konsistent und verwaltungsfähig zu halten.

Wofür können Sie gemeinsam genutzte Pakete verwenden?​

Sie können gemeinsam genutzte Pakete verwenden, um alles gemeinsam zu nutzen, von einfachen Dienstfunktionen bis hin zu UI-Komponenten und Frontend-Abstraktionen.

Die Pakete werden über das Standard-NPM-Protokoll veröffentlicht und installiert, so dass jeder JavaScript- oder TypeScript-Code über diesen Mechanismus freigegeben werden kann.

Das Repository für gemeinsam genutzte Pakete​

Das Repository für gemeinsam genutzte Pakete ist ein Ort, an dem Sie gemeinsam genutzte Pakete definieren, testen, erstellen und veröffentlichen können, die in Ihren verschiedenen Jutro-Apps innerhalb Ihres Guidewire Cloud Tenants wiederverwendet werden können.

Dieses Repository wird für jedes Sternensystem mit Jutro-Anwendungen bereitgestellt. Das bedeutet, dass Sie das Repository für gemeinsam genutzte Pakete verwenden können, um Code und Funktionen für alle Apps in jedem Sternensystem gemeinsam zu nutzen.

shared-packages-star-system

Das Repository ist als Mono-Repository strukturiert und verwendet Standard-NPM-Arbeitsbereiche, um mehrere Pakete in einem einzigen Repository zu verwalten.

Note: Sie können private Registrierungen jetzt mit Ihren eigenen JavaScript- und UI-Komponenten in Ihren Jutro-Apps einrichten. Weitere Informationen finden Sie unter Einrichten der externen Paketregistrierung.

Verteilung von Paketen​

Das Repository für gemeinsam genutzte Pakete veröffentlicht Pakete in Ihrem Namensraum für gemeinsam genutzte Pakete innerhalb des Guidewire Binary Repository als privates Paket.

Das bedeutet, dass kein anderer Kunde auf Ihre gemeinsam genutzten Pakete zugreifen kann, und Sie können nicht auf die gemeinsam genutzten Pakete anderer Kunden zugreifen.

Zusätzlich haben alle veröffentlichten Pakete ein Namensraum-Präfix, das aus @{tenantId}-{starSystemId}/ besteht. Wenn Ihre Tenant-ID beispielsweise acme lautet und Ihre Sternensystem-ID gwcpdev ist, dann werden alle Ihre Pakete unter dem Namensraum @acme-gwcpdev/ veröffentlicht.

Dadurch wird sichergestellt, dass die Pakete für Ihren Tenant und Ihr Sternensystem eindeutig sind und nicht mit anderen Paketen in Konflikt geraten.

Weitere Informationen darüber, wie Sie zuvor veröffentlichte Pakete in einer App installieren können, finden Sie im Abschnitt Konsumieren von gemeinsam genutzten Paketen.

shared-packages-chart

Zugriff auf das Repository für gemeinsam genutzte Pakete​

Um auf das Repository für gemeinsam genutzte Pakete zugreifen zu können, müssen Sie Zugang zur Jutro Digital Platform haben. Sie können von jeder App auf der Seite Jutro Web Apps zum Repository für gemeinsam genutzte Pakete für das jeweilige Sternensystem navigieren. Folgen Sie diesen Schritten, um auf das Repository für gemeinsam genutzte Pakete zuzugreifen.

  1. Melden Sie sich bei Guidewire Cloud an und navigieren Sie dann zu Jutro Web Apps.
  2. Öffnen Sie eine beliebige App.
  3. Klicken Sie auf der Registerkarte Einstellungen im Abschnitt Gemeinsam genutzte Pakete auf den Link Quellcode.

Quellcode

Es gibt auch einen Build management-Link zu die zugehörigen CI-Aufgaben für das Repository der gemeinsam genutzten Pakete. Hier können Sie den Status der Testpipelines der gemeinsam genutzten Pakete einsehen und auch Artefakte veröffentlichen.

Erstellen Sie neue gemeinsam genutzte Pakete, indem Sie dieses Repository lokal klonen. Der Prozess zum Klonen dieses Repositorys folgt denselben Schritten wie das Klonen Ihrer Jutro-App Repositorys aus Einrichten Ihrer lokalen Entwicklungsumgebung.

Erstellung gemeinsam genutzter Pakete​

Das Repository für gemeinsam genutzte Pakete ist als Mono-Repository strukturiert und verwendet NPM-Arbeitsbereiche, um mehrere Pakete im selben Repository zu verwalten.

  1. Melden Sie sich bei Guidewire Cloud an und navigieren Sie dann zu Jutro Web Apps.
  2. Öffnen Sie eine beliebige App.
  3. Wählen Sie auf der Registerkarte Einstellungen auf der linken Seite die Option Gemeinsam genutzte Pakete aus.
  4. Klicken Sie auf den Link Quellcode.
  5. Öffnen Sie das Verzeichnis packages im Repository für gemeinsam genutzte Pakete. Erstellen Sie hier Ihre neuen gemeinsam genutzten Pakete.
Note: Im Verzeichnis packages finden Sie einige Beispielpakete als Platzhalter, die Ihnen zeigen, wie Sie Ihre eigenen Pakete erstellen können.

Es steht Ihnen frei, jedes der Platzhalterpakete zu entfernen oder zu bearbeiten, wenn Sie es für richtig halten.

Platzhalter

Jedes Paket ist ein Standard-NPM-Paket. Es sollte eine unabhängige package.json-Datei und eine src/index.ts-Datei haben, welche die relevanten Funktionen des Pakets exportiert. Abgesehen von diesen Dateien steht es Ihnen frei, die Pakete in dem packages-Verzeichnis so zu strukturieren, wie Sie es für richtig halten. Sie können Tests, Dokumentationen und alle anderen Dateien hinzufügen, die Sie für wichtig erachten.

Note: Die package.json-Datei jedes Pakets hat ein name-Feld, welches das Präfix @{tenantId}-{starSystemId}/ enthält. Damit soll sichergestellt werden, dass das Paket für Ihren Tenant und Ihr Sternensystem eindeutig ist.

Die Pakete werden mit Rollup gebündelt, und die Build-Konfiguration wird in der rollup.config.mjs-Datei im Stammverzeichnis des Repositorys für gemeinsam genutzte Pakete definiert.

TypeScript ist außerdem auf der Stammebene so konfiguriert, dass es standardmäßig für alle Pakete funktioniert.

Warning: Vermeiden Sie nach Möglichkeit die Änderung von Dateien auf Stammebene. Dies vereinfacht die Aktualisierung des Repositorys für gemeinsam genutzte Pakete auf die neuesten Jutro-Versionen.

Verwaltung von Abhängigkeiten​

Die gemeinsam genutzten Pakete können ihre eigenen dependencies und peerDependencies in ihren package.json-Dateien angeben.

Eine Faustregel für die Wahl zwischen dependencies und peerDependencies ist:

  • Wenn die Apps, die das gemeinsam genutzte Paket konsumieren, von dieser Abhängigkeit wissen und seine Version als Singleton kontrollieren müssen, sollte sie sich in peerDependencies befinden.
  • Wenn es sich bei der Abhängigkeit um ein Implementierungsdetail des gemeinsam genutzten Pakets handelt und die Apps, die das Paket konsumieren, nichts davon wissen müssen, sollte sie sich in dependencies befinden.

Um das gemeinsam genutzte Paket in den Tests des gemeinsam genutzten Pakets peerDependencies zu verwenden, müssen Sie es manchmal auch zum devDependencies des gemeinsam genutzten Pakets hinzufügen.

Das liegt daran, dass die Tests des gemeinsam genutzten Pakets im Kontext des gemeinsam genutzten Pakets ausgeführt werden und die peerDependencies zu diesem Zeitpunkt nicht von einer App bereitgestellt werden.

Note: Es wird empfohlen, flexible Semver-Bereiche wie ^10.3.0 für dependencies und peerDependencies in den gemeinsam genutzten Paketen zu verwenden, um die größtmögliche Wiederverwendung von App-Abhängigkeiten zu ermöglichen, wenn sie die gemeinsam genutzten Pakete installieren.

Veröffentlichung gemeinsam genutzter Pakete​

Um ein gemeinsam genutztes Paket zu veröffentlichen, müssen Sie zunächst eine neue Version in der package.json-Datei des Pakets festlegen. Es steht Ihnen frei, jede beliebige Versionierungskadenz zu verwenden, solange sie dem von der semantischen Versionierung definierten Format entspricht. Sie können nur gemeinsam genutzte Pakete aus den Standard- und Release-Zweigen veröffentlichen.

Sie können den Befehl npm version verwenden, um die Version des Pakets zu aktualisieren, und die Änderungen dann in den Standard- oder Release-Zweig übertragen. Alternativ können Sie auch die Version in der package.json-Datei manuell aktualisieren und die Änderungen übergeben.

Beim Veröffentlichen eines gemeinsam genutzten Pakets verwendet die TC-Veröffentlichungspipeline den Standardzweig (Hauptzweig), der in der TC-Konfiguration definiert ist.

Note: Das version auf der Stammebene der package.json-Datei wird nicht für die Veröffentlichung der gemeinsam genutzten Pakete verwendet.

Die jeweilige Version der gemeinsam genutzten Pakete, die veröffentlicht werden soll, ist im package.json innerhalb jedes Pakets definiert.

Sobald die gewünschten Versionen in die package.json-Dateien geschrieben und in den Standardzweig übertragen wurden, können Sie die Pakete veröffentlichen, indem Sie die CI-Aufgabe Publish ausführen, den Sie unter dem Build management-Link im Abschnitt Zugriff auf das Repository für gemeinsam genutzte Pakete finden.

Quellcode

Die Veröffentlichungsaufgabe führt die Tests für alle Pakete durch und veröffentlicht dann die Pakete in Ihrem Namensraum für gemeinsam genutzte Pakete im Guidewire Binary Repository.

Warning: Aktualisieren Sie die Version der Pakete, die Sie veröffentlichen möchten, und übergeben Sie sie vor der Veröffentlichung. Die Veröffentlichungsaufgabe ändert NICHT die Versionen in den package.json-Dateien für jedes Paket.

Alle zuvor veröffentlichten Pakete, deren Version sich nicht geändert hat, werden übersprungen.

Nach erfolgreichem Abschluss der Aufgabe stehen die neuen Versionen der gemeinsam genutzten Pakete zur Installation in jeder Jutro-App im selben Sternensystem zur Verfügung.

Außerdem werden im Repository für gemeinsam genutzte Pakete neue Tags erstellt, die den Commit markieren, mit dem das jeweilige Paket veröffentlicht wurde.

Quellcode

Verwenden von gemeinsam genutzten Paketen​

Um ein gemeinsam genutztes Paket in einer Jutro-App zu verwenden, müssen Sie es zur package.json-Datei der App hinzufügen und dann npm install ausführen, um das Paket zu installieren.

Die Installation dieser Pakete erfordert, dass Ihre Jutro-App:

  • die Registrierung für Ihren Namensraum für gemeinsam genutzte Pakete in der .npmrc-Datei der App angibt,
  • Sie sich mit Ihrem Namensraum für gemeinsam genutzte Pakete innerhalb des Guidewire Binary Repository authentifizieren.

Wenn Ihr Paket beispielsweise den Namen placeholder hat und die ID Ihres Guidewire Tenants acme lautet, würden Sie das Paket in den dependencies-Abschnitt der package.json-Datei einfügen, in dem Sie den Namensraum für gemeinsam genutzte Pakete als Präfix verwenden, etwa so:

{
  "dependencies": {
    "@acme-gwcpdev/placeholder": "1.0.0"
  }
}

Wobei @acme-gwcpdev das @{tenantId}-{starSystemId}-Präfix für den Namensraum Ihrer gemeinsam genutzten Pakete ist.

Außerdem müssen Sie Ihre .npmrc-Datei bearbeiten, um die Registrierung für Ihren Namensraum für gemeinsam genutzte Pakete anzugeben:

@acme-gwcpdev:registry=https://amer.binrepo.guidewire.net/artifactory/api/npm/jutro-acme-all-npm-virtual/

Diese Zeile folgt dem Muster:

@{tenantId}-{starSystemId}:registry=https://{region}.binrepo.guidewire.net/artifactory/api/npm/jutro-{tenantId}-all-npm-virtual/

Note: Die Registrierungs-URL befindet sich auf der Seite Gemeinsam genutzte Pakete auf der Registerkarte Einstellungen Ihrer App. Dies ist die Registrierung, die Sie als Ziel verwenden, wenn Sie sich mit npm login authentifizieren.

registry-url

Authentifizierung mit Ihrem Namensraum​

Die CI-Pipelines für die Jutro-Apps werden sich automatisch bei Ihrem Namensraum für gemeinsam genutzte Pakete im Guidewire Binary Repository authentifizieren und die gemeinsam genutzten Pakete installieren können.

Für die lokale Entwicklung müssen Sie jedoch Ihre .npmrc-Datei mit der Authentifizierung für den Namensraum Ihrer gemeinsam genutzten Pakete einrichten.

Um sich gegenüber diesem Namensraum zu authentifizieren, benötigen Sie den API-Schlüssel, der wie unter Einrichten des erforderlichen Repositorys in Ihrer NPM-Konfiguration beschrieben erzeugt wurde.

Öffnen Sie dann Ihr Terminal und authentifizieren Sie sich mit einem der folgenden Befehle bei Ihrem Namensraum für gemeinsam genutzte Pakete:

# Replace the {tenantId}-{starSystemId} in the following commands with appropriate values

# Using curl, piping the result into .npmrc
curl -u your_email@your_corporate_email.com:your_identity_token https://amer.binrepo.guidewire.net/artifactory/api/npm/jutro-{tenantId}-all-npm-remote/auth/{tenantId}-{starSystemId} >> .npmrc

# Using npm-cli-login (https://www.npmjs.com/package/npm-cli-login)
npx npm-cli-login -u your_email@your_corporate_email.com -p your_identity_token -r https://amer.binrepo.guidewire.net/artifactory/api/npm/jutro-{tenantId}-all-npm-virtual -e your_email@your_corporate_email.com -s @{tenantId}-{starSystemId}

Lokale Entwicklung​

Für die lokale Entwicklung wird empfohlen, die npm-Bibliothek relative-deps zu verwenden.

Der erste Schritt besteht darin, das Paket als dev-Abhängigkeit in dem Projekt zu installieren, aus dem Sie das lokale Paket verwenden möchten

npx relative-deps init

Dieser Befehl installiert sowohl das Paket als auch aktualisiert die package.json-Skripte, so dass relative-deps mit lokal definierten Paketen in npm install synchronisiert werden können. Es wird empfohlen, diese Synchronisierung ebenfalls prestart einzubeziehen, um sicherzustellen, dass Sie jedes Mal, wenn Sie Webpack für Ihre paketnutzende App neu starten, den neuesten Build Ihres Pakets verwenden.

//package.json
{
  "name": "my-app",
  "scripts": {
    "prepare": "relative-deps",
    "prestart": "relative-deps",
  }
}

Jetzt müssen wir das lokale Paket, das wir konsumieren möchten, zu unserer konsumierenden App hinzufügen, indem wir den entsprechenden Pfad hinzufügen. Dies erfolgt durch die Ausführung von

npx relative-deps add ../sharedpackages/packages/placeholder

Dies nimmt das, was in diesem Verzeichnis erstellt wurde, in diesem Fall das Platzhalterpaket, und legt es als Paket in der konsumierenden Projekt node_modules ab.

Die Nutzung dieses neuen Pakets in unserer App ist die gleiche wie bei jedem anderen Paket. Der einzige Unterschied zwischen der lokalen und der remoten Nutzung besteht darin, dass lokal nicht das Tenant-spezifische Bereichspräfix verwendet wird, sondern nur basierend auf dem Namen des Pakets verwendet wird. Diesen Paketnamen finden Sie, indem Sie in Ihrem package.json den Paketnamen sehen, der als Ergebnis der Ausführung des vorherigen Befehls zu relativeDependencies hinzugefügt wurde.

//package.json
{
    "name": "my-app",
    "relativeDependencies": {
        "placeholder": "../sharedpackages/packages/placeholder"
    }
}
//AppPage.tsx

import {SampleComponent} from 'placeholder'
import React from 'react'

export const AppPage:React.FC = () => (
    <SampleComponent />
)

Um Änderungen lokal am Paket vorzunehmen, erstellen Sie das sharedpackages-Projekt npm run build neu, und starten Sie dann basierend auf dem, was Sie in Setup getan haben, entweder die nutzende App npm start neu, oder installieren Sie Pakete npm install neu.