Retail React App in PWA Kit v2.x

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. Dieser Architekturleitfaden für die Retail React App im Progressive Web App (PWA) Kit Version 2.x:

Beschreibt deren Struktur und Inhalt.
Hebt die flexible Open-Source-Grundlage hervor.

Dateistruktur

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.

1.eslintignore                               Exclusion rules for ESLint
2.eslintrc.js                                Code style rules for ESLint
3.gitignore                                  Exclusion rules for git
4.prettierignore                             Exclusion rules for Prettier code formatting
5.prettierrc.yaml                            Code formatting rules for Prettier
6├── app/                                    Application code lives here
7    ├── assets/svg/                         SVG icon assets
8    ├── commerce-api/                       Commerce API client and hooks
9    ├── components/                         React components
10    │   ├── _app                            Root component
11    │   ├── _app-config                     Wrapper component for injecting custom code
12    │   └── _error                          Generic error component
13    │   └── ...
14    ├── constants.js                        Constants imported throughout the app
15    ├── contexts/                           React contexts
16    ├── hoc                                 Contains higher-order components
17    ├── hooks/                              React hooks
18    ├── main.jsx                            Client-side rendering entry point
19    ├── pages/                              Retail-oriented pages like home, PLP, and PDP
20    ├── partials/                           Partials imported throughout the app
21    ├── request-processor.js                Request processing functions (run at CDN edge)
22    ├── request-processor.test.js           Tests for request processing functions
23    ├── routes.jsx                          Maps request paths to route components
24    ├── routes.test.js                      Tests for mapping request paths to route components
25    └── ssr.js                              Server-side rendering entry point
26    ├── static/                             Static assets
27    │   └── manifest.json                   Manifest for PWA features like add to home screen
28    │   └── ...
29    ├── theme/                              Theme files for components
30    │   ├── components/
31    │   │   ├── base/                       Theme files for Chakra UI components
32    │   │   └── project/                    Theme files for custom components
33    │   ├── foundations/                    Frequently used theme values like colors and spacing
34    │   └── index.js
35    ├── translations/                       Translations for react-intl
36    ├── utils/                              Utilities imported throughout the app
37babel.config.js                             Transpilation rules for Babel
38cache-hash-config.json                      Cache breaking hash used by the CDN
39CHANGELOG.md                                Chronological list of changes to the template
40├── config/                                 Configuration files
41    ├── default.js                          Default configuration file
42    ├── mocks/                              Default configuration file with mock values for unit testing
43    └── sites.js                            Identifies sites configured in Business Manager. Includes localization details.
44jest-setup.js                               Unit testing setup for Jest
45jest.config.js                              Unit testing configuration for Jest
46LICENSE                                     Software licensing agreement
47node_modules/                               Package dependencies
48package-lock.json                           Package configuration lock file
49package.json                                Package configuration
50README.md                                   Basic documentation
51tests/                                      Unit tests
52worker/                                     Service worker

Skripte

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.

Testsuiten

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:

1npm run test

Um mehr über das Testen Ihrer Storefront zu erfahren, können Sie die Werbeträgernummer 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:

1npm run test:lighthouse

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.

Salesforce APIs

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.

Note

Auf Käuferdaten in der Retail React 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 config/default.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:

1const MyPage = (props) => {
2  const {categories} = props
3  return <div>There are {categories.length} categories.</div>
4}
5
6MyPage.getProps = async ({api}) => {
7  categories = await api.shopperProducts.getCategory({
8    parameters: {id: categoryId, levels: 0}
9  })
10
11  return {categories}
12}

Der CommerceAPI-Wrapper verwendet derzeit die Commerce API für Produkte, Werbeaktionen, Geschenkgutscheine und Suchen. Jede Funktionalität wird mit einem eigenen Satz von Endpunkten bereitgestellt, die in der B2C Commerce API-Referenzseparat dokumentiert sind.

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.

Chakra UI

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.

Themen

Das Chakra-Themensystem basiert auf der Styled System-Themenspezifikation. Indem Sie die Werte im Verzeichnis app/theme 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 iin der Werbeträgernummer der jeweiligen Seitenkomponenten in app/pages.

Note

SVG-Symbole

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

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.

Weitere Kerntechnologien

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

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.js

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.

Node.js

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

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

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 vorgefertigte 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.

Nächste Schritte

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 die Werbeträgernummer, besonders die E-Commerce-Komponenten in app/pages.
Weitere Informationen zu den neuesten Dateien in der Retail React App und anderen Paketen finden Sie unter GitHub Repository.