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:

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

🪝 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 bietet über TanStack Query viele großartige Funktionalitäten (einschließlich Statusverwaltung usw.). Weitere Einzelheiten hierzu finden Sie in der Commerce SDK React-Dokumentation.

⚛️ Wichtige Aktualisierungen von Anbieterbibliotheken, einschließlich Unterstützung für React 18, Node 16/18 und Chakra 2 und mehr.

Eine der ersten Entscheidungen bei der Migration von v2.7.x auf v3.x ist, ob Sie die Erweiterbarkeit von Vorlagen nutzen wollen. Um in den Genuss der Vorteile dieser Funktionalität zu kommen, müssen Sie mindestens eine Datei aus @salesforcef/retail-react-app (oder einer anderen erweiterbaren App) importieren. Sie können wählen, wie viele Dateien aus der Basisvorlage vererbt werden sollen, aber Sie müssen sich auf den Import mindestens einer Datei festlegen.

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

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.

Bei Projekten, in denen Sie nach der Aktualisierung auf v3 getProps weiterverwenden möchten, umschließen Sie Ihre AppConfig-Komponente mit der withLegacyGetProps-Komponente.

Ändern Sie die Abhängigkeiten in package.json wie folgt:

Aktualisieren Sie die Engines in package.json, damit sie Node 18 und npm 9 unterstützen. Entfernen Sie @chakra-ui/system aus peerDependencies in package.json, da Version 2 die aktuellste Hauptversion von Chakra ist.

Es gibt einen Fehler mit nswapi aufgrund einer Abhängigkeit von jest-environment-jsdom, die mit Chakra 2 nicht kompatibel ist. In einigen Tests, die die Modal-Komponente verwenden, wird folgender Fehler ausgegeben: ':disabled):not([disabled]' is not a valid selector. Dieser Fehler betrifft nur Unit-Tests, nicht die Browser-Ausführung. Wir verwenden npm 8 und erzwingen mithilfe von Überschreibungen Version 2.2.2 des nwsapi-Pakets; Unterstützung für npm 7 wird eingestellt.

Fügen Sie in package.json eine overrides-Eigenschaft hinzu, um die Paketversion zu erzwingen:

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

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örung für Hooks in app/components/forms/*, da das errors-Objekt in das formState-Objekt verschoben wurde.

2. Verschieben Sie die Render-Eigenschaften von Controller in die field-Eigenschaft. Die Rückrufsignatur von Render gibt 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.

Fügen Sie diese Funktion überall dort hinzu, wo Sie bedingtes Rendering verwenden. Es gibt ein paar Stellen, an denen die Funktion in einem PWA Kit-Projekt hinzugefügt werden sollte:

Siehe hier.

Wenn Sie ein Browser-Plug-in installiert haben, das das DOM-Rendering behindert, erhalten Sie möglicherweise einen Hydrationsfehler im Footer. Wenn Sie zum Beispiel die LastPass-Erweiterung verwenden, sehen Sie den Fehler in der Subscribe-Komponente im Footer, da LastPass das Rendering des Browsers übernimmt, um ein Symbol zur Aktivierung des in-field-Popups einzufügen. Wenn diese Übernahme während des Hydrationsprozesses stattfindet, tritt der Fehler auf. Mit einem einfachen Trick können Sie die Reihenfolge der Eingabekomponenten ändern, ohne isHydrated() zu verwenden:

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 Ihr userEvent 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 einen Vergleich zwischen release-2.7.x und release-3.0.x durchführen und nach @salesforce/commerce-sdk-react suchen. Achten Sie in den diff-Ergebnissen auf alle Ergänzungen, die diesen Import hinzufügen.