Die Retail React App
Die Retail React App ist eine Sammlung von Beispielcode und Tools, die Ihnen dabei helfen, Ihre Storefront über APIs zu erstellen und sie auf Managed Runtime zu hosten. Diese Architekturanleitung beschreibt die Struktur und Inhalte der Retail React App und unterstreicht deren flexible Open-Source-Grundlage.
Alle PWA Kit-Projekte beginnen mit der gleichen Gruppe von Dateien. Diese Dateien werden zu Beginn eines Projekts durch Ausführung eines Skripts erzeugt. (Dieser Prozess wird umfassend in der Anleitung Erste Schritte beschrieben.)
Anhand der Dateistruktur können Sie sich einen Überblick über die Funktionsweise der Retail React App verschaffen. Hier ist eine Liste aller Dateien und Verzeichnisse eines neu erzeugten Projekts. Zu jedem Element finden Sie auch eine kurze Beschreibung. Die in den Beschreibungen erwähnten Technologien werden später in dieser Anleitung ausführlicher behandelt.
Zur Automatisierung routinemäßiger Entwicklungsaufgaben enthält die Retail React App mehrere Skripte. Verwenden Sie den Befehl npm run <SCRIPT_NAME>, um sie über das Terminal auszuführen.
Hier ist eine vollständige Liste der inbegriffenen Skripte mit einer Beschreibung:
| Name | Beschreibung |
|---|---|
analyze-build | Baut das Projekt im Production-Modus und erstellt zwei Webpack-Bundle-Analyzer-Berichte. Anhand dieser Berichte können Sie die Größe Ihres Codebündels überwachen. |
compile-messages | Kompiliert alle lokalisierten Meldungen im AST-Format. |
extract-messages | Extrahiert automatisch die Meldungen des Standard-Gebietsschemas Ihrer React-Komponenten. |
format | Formatiert den Code mit Prettier. |
lint | Sucht mit ESlint nach Unstimmigkeiten im Code. |
lint:fix | Behebt ESlint-Fehler automatisch. |
prod:build | Baut das Projekt im Production-Modus. |
push | Pusht das Codebündel (Production-Build-Artefakte) in Managed Runtime. |
save-credentials | Speichert die Runtime Admin-Anmeldedaten lokal (für Push-Befehl). |
start | Startet den SSR-Server. |
start:inspect | Startet den SSR-Server unter Verwendung des Node.js-Inspektors. |
start:pseudolocale | Startet den SSR-Server mit einem Pseudo-Gebietsschema. |
test | Führt Unit-Tests unter Verwendung von Jest durch. |
test:lighthouse | Führt Lighthouse-Tests durch. |
test:max-file-size | Führt einen Test der Bündelgröße durch. |
Zum Zweck der Qualitätssicherung enthält Ihr Projekt zwei Bespiel-Testsuiten: Unit-Tests, die mit Jest und der React Testing Library erstellt wurden.
Diese Unit-Tests finden Sie zu jeder der Seitenkomponenten in ihrem jeweiligen Verzeichnis.
Führen Sie zum Start der Unit-Tests den folgenden Befehl in Ihrem Terminal aus:
Um mehr über das Testen Ihrer Storefront zu erfahren, können Sie den Quellcode der Beispiel-Testsuiten und die Dokumentation zu Jest und der React Testing Library durchgehen.
Die Lighthouse-Testsuite von Google hat gemessen, dass die Retail React App von Anfang an hervorragende Leistungswerte erreicht. Mit dem folgenden Skript ist die Überwachung Ihrer Lighthouse-Werte während der Entwicklung noch einfacher:
Das Skript führt Lighthouse dreimal auf Ihrer Storefront aus und lädt die Mittelwerte der einzelnen Kategorien bei Google hoch. Anhand dieser Zahlen erstellt Google dann einen Bericht. Bevor das Skript beendet wird, gibt es einen Link zu diesem Bericht aus.
Um Salesforce APIs für den Zugriff auf Käuferdaten verwenden zu können, muss ein Administrator die in Einrichtung des API-Zugriffs beschriebenen Aktionen durchführen.
Auf Käuferdaten in der React Retail App wird über eine Klasse namens CommerceAPI zugegriffen, die auf dem commerce-sdk-isomorphic-Client aufbaut. Sie können die CommerceAPI-Klasse in app/commerce-api/index.js anpassen und in app/api.config.js konfigurieren.
Die CommerceAPI-Klasse wird automatisch in die getProps-Methode injiziert. Beispiel: Sie können auf den API-Wrapper über eine Seitenkomponente wie folgt zugreifen:
Der CommerceAPI-Wrapper verwendet derzeit die Commerce API für Produkte, Werbeaktionen, Geschenkgutscheine und Suchen. Jede dieser Funktionalitäten wird mit ihrem eigenen Satz von Endpunkten bereitgestellt, die separat in der Referenzdokumentation B2C Commerce API beschrieben werden.
Zur Autorisierung von API-Anfragen im Namen von registrierten Käufern und Gästen stützt sich die CommerceAPI-Klasse auf eine Salesforce Commerce API namens Shopper Login and API Access Service (SLAS).
Für Warenkörbe und Bestellungen verwendet die CommerceAPI-Klasse auch die Open Commerce API (OCAPI).
Anweisungen für die Einrichtung der Salesforce Commerce API (einschließlich SLAS) und von OCAPI finden Sie in Einrichtung des API-Zugriffs.
Die Komponentenbibliothek Chakra UI ist eine neue, aber Production-bereite Technologie, die in der Retail React App ihre Leistung unter Beweis stellt. Die Bibliothek enthält mehr als 50 UI-Komponenten mit hervorragender Zugänglichkeit und Benutzerfreundlichkeit. Die Komponenten können mit Style Props angepasst werden. Für erweiterte Stiloptionen (CSS-in-JS) sind JavaScript-Objekte verfügbar. Alle Chakra-Komponenten verfügen über sorgfältig designte Grundstile, die mit einem Themensystem überschrieben werden können.
Das Chakra-Themensystem basiert auf der Styled System-Themenspezifikation. Indem Sie die Werte im app/theme-Verzeichnis aktualisieren, können Sie das Look-and-feel Ihrer Komponenten markenspezifisch anpassen.
Themen sind für die meisten der wiederverwendbaren Komponenten in app/components verfügbar, aber nicht für Seiten wie die Produktdetailseite oder Produktlistenseite. Wenn Sie den Stil dieser Seiten ändern möchten, bearbeiten Sie die Inline-Stile im Quellcode der jeweiligen Seitenkomponenten in app/pages.
Wenn Sie im Projekt benutzerdefinierte SVG-Symbole verwenden möchten, fügen Sie sie im app/assets/svg-Verzeichnis hinzu, importieren Sie sie in app/components/icons/index.js und exportieren Sie die React icon-Komponente wie folgt: export const MyCustomIcon = icon('my-custom-icon').
Die importierten SVG-Symbole werden zum Zeitpunkt des Builds in ein SVG-Sprite verpackt, das in den serverseitig gerenderten HTML-Code eingebunden wird.
Das PWA Kit React SDK ist eine Bibliothek mit Unterstützung für die isomorphe Rendering-Pipeline für PWA Kit-Storefronts. Das SDK enthält viele Schlüsselklassen, Funktionen und Komponenten für die Retail React App. Beispiel: Die Funktion render() in app/ssr.js, die den gesamten Rendering- und Routing-Prozess startet, wird aus dem SDK importiert.
Für größere Benutzerfreundlichkeit blendet das SDK einige der Implementierungsdetails für serverseitiges Rendering, Caching und Proxyvorgänge aus und bietet Ihnen gleichzeitig zahlreiche Möglichkeiten, diese Vorgänge anzupassen. Es stellt darüber hinaus allgemeine Dienstprogramme und Werkzeuge für die Pflege eines einzigen Codesatzes bereit, der sowohl auf der Client- als auch auf der Serverseite gerendert werden kann.
Für die einfachere Implementierung von Verbesserungen stellt Salesforce das SDK als separates npm-Paket neben der Retail React App bereit.
Sowohl das PWA Kit React SDK als auch die gesamte Retail React App sind Open-Source-Projekte und bei GitHub verfügbar. Wir freuen uns über Beiträge der Commerce Cloud Community.
Bei den in diesem Abschnitt aufgeführten Open-Source-Technologien handelt es sich um die von der Retail React App am häufigsten verwendeten Technologien. Dies sind auch die Technologien, die sich nur schwer durch Alternativen ersetzen lassen. Wir haben sie nicht nur aufgrund ihrer Leistungseigenschaften, sondern auch wegen ihres Rufs ausgewählt. Jede dieser Technologien wird aktiv gepflegt, ist in hohem Maße anpassbar, gut dokumentiert und weitverbreitet.
Hier ist eine kurze Übersicht über jede dieser Kerntechnologien. Mit vielen davon sind Sie sicherlich bereits vertraut:
Babel kompiliert Ihren JavaScript-Code, damit er mit einer Vielfalt von Browsern und Node.js-Umgebungen kompatibel ist. Dabei wird erweiterte Sprachsyntax transformiert und alle in der Umgebung fehlenden Funktionalitäten werden mittels Polyfill "nachgerüstet".
Express ist ein gängiges in JavaScript geschriebenes Open-Source-Webserver-Framework, das innerhalb der Node.js-Laufzeitumgebung ausgeführt wird. Express handhabt HTTP-Anfragen für die von Ihnen als Einstiegspunkte für Ihre Storefront definierten Routen.
Express ermöglicht Ihnen, allgemeine Webserver-Einstellungen, wie den Verbindungsport und den Speicherort von Vorlagen für die Rückgabe der Antwort, zu konfigurieren. Mit Express können Sie darüber hinaus an jeder Position der anfragenbearbeitenden Pipeline zusätzliche anfragenbearbeitende Middleware hinzufügen.
Der gesamte serverseitige Code einer PWA Kit-Anwendung wird auf Node.js, einer Open-Source-Laufzeitumgebung für JavaScript, ausgeführt. Die Laufzeitumgebung lässt browserspezifische JavaScript-APIs aus und schließt dafür ihre eigenen APIs ein, um plattformübergreifend auf Funktionalitäten des Host-Betriebssystems (wie das Dateisystem) zuzugreifen.
Node.js verwendet eine Non-Blocking- oder asynchrone Architektur, die für den Aufbau von hoch skalierbaren und datenintensiven Storefronts ideal ist.
React ist ein von Facebook entwickeltes Framework für die Erstellung von Einzelseitenanwendungen, die schnelle, flüssige und immersive Benutzerschnittstellen liefern.
In einer React App besteht die Benutzeroberfläche aus separaten Komponenten, die in der Regel in komplexen Hierarchien angeordnet sind. In einer gut durchdachten React App ist eine Einzelkomponente nur für eine einzige Aufgabe zuständig. Oft besteht diese Aufgabe nur darin, weitere Komponenten zu enthalten.
Die Komponentenhierarchie in der Retail React App ist auf Erweiterbarkeit angelegt. Sie können auf den inbegriffenen Komponenten aufbauen oder diese gegen neue Komponenten austauschen.
React-zugehörige Pakete:
| Name | Beschreibung |
|---|---|
| Loadable Components | Beschleunigt durch Code-Splitting größerer Bündel die Leistung. |
| ReactDOM | Stellt DOM-spezifische Methoden bereit, die auf der obersten Ebene Ihrer Anwendung verwendet werden können. |
| ReactDOMServer | Stellt die Methode renderToString() bereit, die HTML serverseitig vorrendert. |
| React Helmet | Unterstützt die Verwaltung von am head-Tag des Dokuments vorgenommenen Änderungen. |
| React Router | Ordnet den React-Komponenten URL-Pfade zu. Pfade können als Muster ausgedrückt werden, die beginnend mit der spezifischsten bis zur unspezifischsten Form abgeglichen werden. |
Webpack fasst Ihren Code in einem oder mehreren Bündeln zusammen. Die Bündel werden dann in Managed Runtime bereitgestellt und schließlich im Rahmen des Hydrationsprozesses in den Browser geladen.
Die Retail React App importiert gebrauchsfertige Webpack-Konfigurationen für die Client- und Serverseite aus dem PWA Kit React SDK. In den meisten Fällen müssen Sie diese Konfigurationen nicht mehr ändern, aber sollten Sie dies tun, können Sie die Webpack-Konfiguration in webpack.config.js erweitern.
Jetzt sind Sie mit der Struktur und den Inhalten der Retail React App vertraut und können sich näher mit den Details beschäftigten. Erkunden Sie als Erstes den Quellcode, besonders die E-Commerce-Komponenten in app/pages.