Einrichtung Ihrer lokalen Umgebung

In dieser Anleitung wird erklärt, wie Sie Ihre lokale Umgebung für die Entwicklung mit dem PWA Kit einrichten.

Für die Entwicklung mit dem PWA Kit empfehlen wir die Verwendung eines Unix-basierten Betriebssystems. Dazu zählen:

Windows 10 mit installiertem Windows Subsystem für Linux
macOS 10.13 oder höher
Ubuntu Linux 18.x oder höher

Windows-Benutzer: Siehe offizielle Empfehlungen von Microsoft für Node-Entwickler.

Sie müssen spezifische Versionen von Node und Node Package Manager (NPM) installieren, die von Managed Runtime unterstützt werden.

Laden Sie den für Ihr Gerät passenden Installer von der Downloadseite für Node 18.x herunter.

Windows-Benutzer: Laden Sie die Ihrem Prozessor entsprechende .msi-Datei herunter. Beispiel: Bei einem 64-Bit-Intel-Prozessor wählen Sie den x64-Installer.

Mac-Benutzer: Laden Sie die Datei .pkg herunter.

Apple Silicon-Benutzer: Falls Sie Rosetta nicht bereits installiert haben, führen Sie softwareupdate --install-rosetta aus.

Linux-Benutzer: Laden Sie die Ihrem Prozessor entsprechende -linux-Datei herunter. Beispiel: Bei einem 64-Bit-Intel-Prozessor wählen Sie den linux-x64-Installer in Ihrem bevorzugten Archivformat.

Öffnen Sie nach dem Herunterladen den korrekten Node Installer und befolgen Sie die Anweisungen für die Einrichtung.

Akzeptieren Sie auf Aufforderung des Installers hin die Standardoption, ebenfalls die Node.js-Laufzeitumgebung zu installieren, installieren Sie den Node Package Manager und fügen Sie die Node.js-Laufzeitumgebung zu Ihrem Pfad hinzu.

Prüfen Sie vor dem Fortsetzen, dass Sie die korrekten Versionen von Node und NPM installiert haben:

Öffnen Sie ein Terminal.
Führen Sie node -v aus.
Bestätigen Sie, dass v18.16.1 (bzw. die neueste 18.x-Version) zurückgegeben wird.
Führen Sie npm -v aus.
Bestätigen Sie, dass 9.5.1 (bzw. die neueste bei Node 18.x inbegriffene Version) zurückgegeben wird.

Sollten Sie eine andere Version von NPM installiert haben, können Sie Version 9.5.1 wie folgt manuell installieren:

Öffnen Sie ein Terminal.
Führen Sie npm install -g npm@9.5.1 aus.
Führen Sie npm -v erneut aus.
Bestätigen Sie, dass 9.5.1 zurückgegeben wird.

Wenn Sie auf Windows mehrere Node-Versionen verwalten möchten, sollten Sie Node Version Switcher oder Volta verwenden. Den Node Version Manager (NVM) für Windows von Corey Butler empfehlen wir nicht, da während unserer Tests Probleme damit aufgetreten sind.

Für Mac- und Linux-Benutzer empfehlen wir die Installation von Node Version Manager.

Jede PWA Kit-Storefront muss für die Verwaltung von Bereitstellungen über ein in Runtime Admin erstelltes Projekt verfügen.

Bevor Sie Managed Runtime und Runtime Admin verwenden können, müssen sie aktiviert sein, und Sie müssen Zugriff darauf anfordern. Um Managed Runtime und Runtime Admin für Ihre Organisation zu aktivieren, wenden Sie sich an Ihr Salesforce Account-Team. Um Zugriff zu erhalten, bitten Sie Ihren Commerce Cloud-Administrator, Ihrem Konto mithilfe des Account Managers eine der folgenden Rollen hinzuzufügen: Managed Runtime User oder Managed Runtime Admin.

Sollten Sie oder jemand in Ihrem Team dies nicht bereits getan haben, erstellen Sie mit den folgenden Schritten ein Projekt in Runtime Admin:

Melden Sie sich in Runtime Admin an.
Klicken Sie auf New Project (Neues Projekt).
Geben Sie einen Namen für das Projekt ein.
Klicken Sie auf Create Project (Projekt erstellen).

Notieren Sie sich die Projekt-ID, denn sie wird im Rahmen der Entwicklung für die Erzeugung von Projektdateien benötigt.

Auf Ihre Website kann nach der anfänglichen Erstellung eines Projekts erst dann online zugegriffen werden, wenn die erforderliche Cloud-Infrastruktur bereitgestellt worden ist. Dieser Bereitstellungsprozess kann bis zu 40 Minuten dauern.

Um mehr darüber zu erfahren, was Sie in Runtime Admin machen können, ziehen Sie unsere Anleitung Managed Runtime Administration zurate.

Die meisten PWA Kit-Entwickler klonen zuerst ein Repository mit einem zuvor erzeugten Satz von Projektdateien. (Springen Sie zum nächsten Abschnitt, um zu erfahren, wie Sie ein neues Projekt erzeugen.)

Nach dem Klonen des Projekt-Repositorys müssen Sie Paketabhängigkeiten installieren:

Öffnen Sie ein Terminal.
Wechseln Sie in das Projektverzeichnis.
Führen Sie npm ci aus.

Wenn Sie bereits ein vorhandenes PWA Kit-Projekt haben und die Anweisungen im vorhergehenden Abschnitt abgeschlossen haben, können Sie mit dem nächsten Abschnitt weitermachen. Ansonsten müssen Sie jetzt zuerst ein Projekt erzeugen.

Öffnen Sie dazu einen Terminal und führen Sie den folgenden Befehl aus. Ersetzen Sie ~/PLACEHOLDER-PROJECT-ID mit einem Pfad, der die Projekt-ID aus Runtime Admin enthält:

Im Befehl npx können Sie @latest durch eine bestimmte Version der Retail React App ersetzen, beispielweise durch @v3.0.0 oder @v2.7.3. Wenn Sie keine Version festlegen, können Sie durch das Caching älterer Versionen unerwartete Ergebnisse erhalten.

Wenn Sie zur Auswahl einer Projektvoreinstellung aufgefordert werden, wählen Sie eine der folgenden Optionen aus:

retail-react-app-demo: Verwenden Sie die Storefront-Vorlage der Retail React App und die Demo-Sandbox als Backend. Es ist keine weitere Konfiguration erforderlich.
retail-react-app: Verwenden Sie die Storefront-Vorlage der Retail React App und Ihre eigene B2C Commerce Instanz als Backend. Sie müssen Konfigurationswerte eingeben.

Bei Verwendung der retail-react-app-Voreinstellung werden Sie vom Generator-Skript zur Eingabe mehrerer Konfigurationswerte aufgefordert. Diese Konfigurationswerte verknüpfen Ihr neues PWA Kit-Projekt mit einem entsprechenden Projekt im Runtime Admin-Tool und einer B2C Commerce Instanz.

Die folgende Tabelle enthält nähere Informationen zu den einzelnen Produktkonfigurationswerten und wo Sie diese finden. Die Konfigurationswerte werden in der Dokumentation der B2C Commerce API ausführlicher behandelt. Siehe Base URL and Request Formation (Bildung von Basis-URL und Anfrage).

Konfigurationswert	Weitere Informationen
Projekt-ID in Managed Runtime Admin	In Managed Runtime Administration wird erklärt, wie Sie ein Projekt erstellen und die Projekt-ID eines vorhandenen Projekts feststellen. Beispiel: `example-project`
URL für Ihre B2C Commerce Instanz	Brauchen Sie für die Entwicklung oder das Testen eine neue B2C Commerce Instanz? Siehe Erstellung einer On-Demand Sandbox. Beispiel: `https://zzdc-001.dx.commercecloud.salesforce.com`
Commerce API Client-ID	Diese Kennung befindet sich nicht mehr im Account Manager. Siehe Generierung einer Client-ID für den API-Zugriff. Beispiel: `1adba44c-ee9b-41f9-b4bf-1bbc3dda1967`
Privater Client-Modus der Commerce API	Hier entscheiden Sie, ob Ihre Anwendung einen öffentlichen oder privaten Authentifizierungs-Workflow für die Anmeldung von Käufern verwendet. Weitere Informationen finden Sie in der Dokumentation zur Anmeldung von Käufern sowie unter Verwendung eines privaten SLAS Client. Standard: `true`
Website-ID im Business Manager	Zur Identifikation einer bestimmten E-Commerce-Website verwendete Zeichenfolge. Im Business Manager finden Sie unter Administration > Websites > Websites verwalten eine Liste der verfügbaren Websites mit ihren Website-IDs. Beispiel: `RefArch`
Commerce API Organisations-ID im Business Manager	Auf Realm und Instanz basierende Zeichenfolge für die Identifikation Ihrer Organisation für den API-Zugriff. Diese Organisations-ID finden Sie im Business Manager unter Administration > Website-Entwicklung > Salesforce Commerce API Einstellungen. Beispiel: `f_ecom_zzdc_001`
Commerce API Kurzcode im Business Manager	Eine aus acht Zeichen bestehende Zeichenfolge, die einem Realm zu Routing-Zwecken zugewiesen wird. Der Kurzcode gilt instanzübergreifend für Ihre gesamte Realm-Umgebung. (Der Kurzcode für alle On-Demand-Sandboxes lautet `kv7kzm78`.) Ihren Kurzcode finden Sie im Business Manager unter Administration > Website-Entwicklung > Salesforce Commerce API Einstellungen. Beispiel: `kv7kzm78`
API Client-ID im Einstein Configurator	Siehe Dokumentation der Einstein API für Commerce Cloud-Entwickler und direkten Zugriff auf den Einstein Configurator.

Nach der Erzeugung eines Projekts empfehlen wir, die erzeugten Projektdateien in einem Repository zu speichern und das Repository für Ihre Storefront-Entwickler freizugeben.

Sie können die Konfigurationswerte eines Projekts auch nach dessen Erzeugung bearbeiten. Näheres hierzu finden Sie in Konfigurationsdateien.

Vergessen Sie nicht, die Konfiguration bei Änderungen dieser Werte zu aktualisieren, beispielsweise nach einer Anpassung der Projektdateien für die Verwendung mit einer anderen B2C Commerce Instanz.

Starten Sie Ihren lokalen Webserver für die lokale Entwicklung von Ihrem Projektverzeichnis aus mit dem folgenden Befehl:

Jetzt, da der Entwicklungsserver läuft, können Sie einen Browser öffnen und sich eine Vorschau Ihrer Storefront anzeigen lassen:

Gehen Sie zu http://localhost:3000/

Mit dem Tastenkürzel Control+C können Sie den Entwicklungsserver jederzeit stoppen.

Um eine Vorschau einer serverseitig gerenderten Seite zu erhalten, hängen Sie die Abfrage-String ?__server_only der URL an, die Sie einsehen möchten. Beispiel: Verwenden Sie die URL www.example.com?__server_only, um sich die serverseitig gerenderte Version von www.example.com anzeigen zu lassen.

Nach dem Klonen eines vorhandenen Projekts und der Ausführung von npm ci oder der Erstellung eines neuen Projekts kann es einige Minuten dauern, bis Sie eine Aktivität im Terminal sehen. Brechen Sie den Prozess nicht vorzeitig ab. Auch Virenschutzsoftware (besonders auf Windows) kann dazu führen, dass Installationen wesentlich mehr Zeit als normal in Anspruch nehmen.
Wenn Sie vom authorize-Endpunkt eine HTTP-401-Fehlermeldung erhalten, gibt es ein Problem mit dem Shopper Login and API Access Service (SLAS). Anweisung zur Korrektur Ihrer SLAS-Konfiguration finden Sie in Einrichtung des API-Zugriffs.

Erstellen und Anpassen