Aktualisierung auf v3

Ab v3 ist es möglich, @salesforce/retail-react-app-Aktualisierungen anzuwenden, indem Sie sie als eine npm-Abhängigkeit hinzufügen und die Erweiterbarkeit von Vorlagen in Ihrem Projekt aktivieren.

Diese Anleitung beschreibt die Vorgehensweise bei der Aktualisierung eines PWA Kit-Projekts von v2.7.x auf v3.0.0.

Wir haben PWA Kit v3 jede Menge neue Funktionalitäten hinzugefügt, unter anderem:

⚛️ Erforderlich:

  • getProps – grundlegende Änderung
  • Wichtige Aktualisierungen von Bibliotheken, einschließlich Unterstützung für React 18, Node 18, Chakra 2 und mehr

🔨 Optional: Erweiterbarkeit von Vorlagen – Reduzieren Sie den Fußabdruck des Codes Ihres Projekts und verringern Sie Entwicklungsaufwand, Betriebskosten sowie Ihr Kopfzerbrechen, das zukünftige Upgrades mit sich bringen können. Nähere Details finden Sie im Leitfaden Erweiterbarkeit von Vorlagen.

🪝 Optional: Integration von @salesforce/commerce-sdk-react "Hooks" – Entkoppelt API-Aufrufe von der Implementierung eines Projekts, erlaubt ein Upgrade von API-Aufrufen als Abhängigkeit einer npm-Bibliothek und bringt viele der wunderbaren Funktionalitäten (einschließlich Statusverwaltung usw.) über eine TanStack-Abfrage. Weitere Einzelheiten hierzu finden Sie in den Commerce SDK React-Dokumenten.

Die PWA Kit SDKs wurden in die @salesforce NPM-Organisation verschoben. Zur Aktualisierung auf v3 installieren Sie die neuen Pakete und ersetzen Sie alle Importanweisungen für die folgenden Pakete:

  • pwa-kit-react-sdk -> @salesforce/pwa-kit-react-sdk@^3
  • pwa-kit-runtime -> @salesforce/pwa-kit-runtime@^3
  • pwa-kit-dev -> @salesforce/pwa-kit-dev@^3
  • pwa-kit-create-app -> @salesforce/pwa-kit-create-app@^3
  • retail-react-app -> @salesforce/retail-react-app@^3

Ab Version 3.0.0 führt PWA Kit mit withReactQuery eine neue Strategie zum Abrufen von Daten ein. Diese Strategie verwendet die Bibliothek "react-query" und ermöglicht es Ihnen, React-Hooks zu schreiben, um Daten isomorph abzurufen. Im Gegensatz zu getProps müssen Sie die Datenabruflogik für die Client- und die Serverseite nicht mehr duplizieren. In dieser Version verwendet @salesforce/retail-react-app standardmäßig @salesforce/commerce-sdk-react (unterstützt von react-query).

  • Sie können withReactQuery und withLegacyGetProps gleichzeitig verwenden.
  • getProps und shouldGetProps wurden aus der Standardvorlage für Seiten der Retail React App entfernt, sind aber nicht veraltet. Die langfristige Unterstützung dieser Methoden bleibt bestehen.

Ändern Sie die Abhängigkeiten in package.json wie unten gezeigt. Entfernen Sie @chakra-ui/system aus peerDependencies und fügen Sie dies unter dependencies oder devDependencies ein.

Aktualisieren Sie die Engines in package.json, um Node 18 und npm 9 zu unterstützen.

Installieren Sie die Abhängigkeiten für Ihr Projekt mit npm i neu.

Bei der Migration von v2.7.x auf v3.x können Sie auswählen, ob Sie die Erweiterbarkeit von Vorlagen verwenden möchten. Um davon zu profitieren, müssen Sie mindestens eine Datei aus @salesforce/retail-react-app (oder eine andere erweiterbare, künftige Vorlage) importieren.

Überlegen Sie dann, wie viele Dateien Sie im mit npx pwa-kit-create-app@2.x generierten Originalprojekt geändert haben. Einige Kunden arbeiten mit vielen Dateien (möglicherweise Hunderten), aber selbst in diesen Fällen wurden viele davon möglicherweise nicht geändert. Diese unveränderten Dateien sind gute Kandidaten für den Import aus @salesforce/retail-react-app, aber Sie sollten diesen Prozess vorsichtig und mit jeweils nur einer begrenzten Anzahl von Dateien durchführen. Viele Dateien in @salesforce/retail-react-app sind ähnlich, aber ihr früherer Zustand in v2.x der Retail React App von PWA Kit wurde inzwischen geändert. Insbesondere die @salesforce/commerce-sdk-react-Integration (Einzelheiten zur Migration werden später ausführlicher behandelt) hat dazu geführt, dass eine große Anzahl von Dateien bezüglich ihrer Importe und ihrer Dateistruktur geändert wurden, wobei das gesamte commerce-api-Verzeichnis - der Ausgangspunkt vieler Vorgänge - aus der App entfernt wurde, was eine Änderung mit erheblichen Auswirkungen darstellt.

Wenn Sie ein Projekt zur Nutzung der Erweiterbarkeit von Vorlagen migrieren, ist zu beachten, dass Version 2.x der PWA Kit-SDKs und der mit npx pwa-kit-create-app@2.x generierten Projekte keine Abhängigkeit von @salesforce/commerce-sdk-react besitzen, während der neuere Code @salesforce/retail-react-app@^1.x diese Bibliothek, die mit viele Dateien interagiert und viele davon ändert, intensiv nutzt. Um eine Vorstellung des Ausmaßes dieser Änderungen zu bekommen, können Sie in diesem GitHub Diff https://github.com/SalesforceCommerceCloud/pwa-kit/compare/release-2.7.x...release-3.0.x?diff=unified#files_bucket einen Vergleich zwischen release-2.7.x und release-3.0.x durchführen. Suchen Sie nach @salesforce/commerce-sdk-react und achten Sie auf alle Ergänzungen, die diesen Import hinzufügen.

Wenn Ihre App versucht, Code gemeinsam mit Version 2.x (einschließlich des Verzeichnisses app/commerce-api) zu nutzen, besteht die Gefahr, dass Sie Ihrem Bündel unnötigen Code in den Fällen hinzufügen, in denen dieser Code (in zwei sehr unterschiedlichen Formen) in sowohl dem commerce-api-Ordner als auch dem npm-Modul @salesforce/commerce-sdk-react verwendet wird.

Ab v3.0.0 verwendet PWA Kit eine andere Fetch-Strategie: withReactQuery. Diese Strategie nutzt die React Query-Bibliothek und ermöglicht Abfragen im SSR-Renderdurchgang. Die @salesforce/retail-react-app verwendet @salesforce/commerce-sdk-react mit Unterstützung durch react-query.

Damit Hooks auf der Serverseite funktionieren, müssen Sie Ihre AppConfig-Komponente mit der neuen übergeordneten Komponente withReactQuery umschließen.

Im Rahmen der Migration zu ReactQuery als Standard-Fetch-Strategie, @salesforce/retail-react-app@^1, ist eine Änderung erforderlich, um zu gewährleisten, dass veraltete getProps()-Aufrufe weiterhin funktionieren.

Nach dem Aktualisieren der oben beschriebenen Abhängigkeiten können in Ihrem Projekt Probleme im Zusammenhang mit folgenden Bibliotheken auftreten. In den nachstehenden Abschnitten finden Sie Tipps zur Lösung dieser Probleme. Da jedes Projekt im Detail anders ist, sind diese Lösungsvorschläge als Richtlinien und nicht als absolute Regeln zu betrachten.

Lesen Sie zur react-hook-form-Migration die offizielle react-hook-form-Dokumentation. Im PWA-Projekt müssen zwei Stellen geändert werden:

  1. Verschieben Sie das "form errors"-Objekt in eine weitere Ebene der Zerstörungsebene für Hooks in app/components/forms/, da das errors-Objekt in das formState-Objekt verschoben wurde.
  1. Verschieben Sie die Render-Eigenschaften von Controller in die field-Eigenschaft. Die Rückrufsignatur von Rendergibt ein Objekt zurück, das field und fieldState enthält.

Ab React 18 werden Hydrationswarnungen nicht mehr wie in React 17 als Warnungen, sondern als Fehler angezeigt. Zur Unterdrückung dieser potenziellen Fehler, die bei Vorhandensein von Hydrationsfehlern die Erstellung der Anwendung verhindern, waren einige Code-Aktualisierungen erforderlich. Diese Fehler müssen unbedingt behoben werden, um zu gewährleisten, dass die App isomorph rendern kann. Dieser Fehler tritt aufgrund einer Diskrepanz zwischen Server oder Client auf. Beim bedingten Rendering einer Komponente oder einer Seite müssen Sie sicherstellen, dass die Hydration vor dem Rendering von clientspezifischem Code abgeschlossen ist.

Erstellen Sie in Ihrem Projekt eine Hilfsfunktion, die feststellt, ob die Hydratation abgeschlossen ist. Sie können eine integrierte Variable verwenden, die von window.__HYDRATING__ in pwa-kit-react-sdk bereitgestellt wird.

Wenn Ihr Projekt Komponenten und APIs aus der Bibliothek @chakra-ui/react verwendet, die sich von denen der Retail React App-Vorlage unterscheiden, lesen Sie die offizielle Dokumentation zur Chakra 2-Migration.

Zur Unterstützung von Chakra 2 müssen einige Dateien für auf der Retail React App-Vorlage basierende Projekte aktualisiert werden.

Entfernen Sie allowToggle in der Accordion-Komponente, da allowMultiple und allowToggle in Chakra 2 nicht gleichzeitig verwendet werden können.

In der Footer-Komponente ist der direkte Import von StylesProvider aus @chakra-ui/react veraltet. Sie müssen ihn stattdessen über createStylesContext('Footer') erstellen.

Richten Sie userEvent ein, bevor Sie eine Aktion aufrufen, und warten Sie in Unit-Tests, die userEvent verwenden, auf die Aktion, da in der React-Testbibliothek v14.0.0 alle Benutzeraktionen asynchron sind und der Aufruf von setup vor der Durchführung von Benutzeraktionen erforderlich ist.

Beispiel:

Weitere Einzelheiten finden Sie in der offiziellen Dokumentation für userEvent aus der Testing-Bibliothek.

Um den wiederholten Aufruf von setup() in vielen Unit-Tests zu vermeiden, können Sie alternativ hierzu IhruserEvent in app/utils/test-util.js unmittelbar vor dem Rendern der Testkomponenten einrichten und diesen Wert zusammen mit den Render-Ergebnissen zurückgeben, sodass der Test die Benutzeraktionen durchführen kann, ohne setup() aufrufen zu müssen.

In einem Jest-Setup gibt es eine Mock-Abhängigkeit, die eine Fehlermeldung dahingehend auslösen kann, dass TextDecoder in jest-setup.js. nicht definiert ist. Fügen Sie Folgendes zu jest-setup.js hinzu:

Bei der Migration von Version 2.x der PWA Kit-SDKs und der über npx pwa-kit-create-app@2.x generierten Projekte wurde der @salesforce/commerce-sdk-react-Code wesentlich überarbeitet, um das app/commerce-api/-Verzeichnis zu entfernen. Anstelle dieser Dateien, die API-Anfragen handhaben und als SDK fungieren, ersetzt @salesforce/commerce-sdk-react diese Funktion. Die Release v3 der SDKs korreliert mit der ersten Release von @salesforce/retail-react-app@^1.x, da die SDKs diese Bibliothek häufig verwenden.

Die Implementierung von @salesforce/commerce-sdk-react verändert viele Dateien in der Retail React App. Um eine Vorstellung des Ausmaßes dieser Änderungen zu bekommen, können Sie in diesem GitHub Diff release-2.7.x und release-3.0.x vergleichen und nach @salesforce/commerce-sdk-react suchen. Achten Sie in den diff-Ergebnissen auf alle Ergänzungen, die diesen Import enthalten.