Mettre à jour vers la version 3

À partir de la version 3, il est possible d’obtenir des mises à jour de @salesforce/retail-react-app en l’ajoutant en tant que dépendance npm et en activant l’extensibilité des modèles dans votre projet.

Ce guide explique comment mettre à jour un projet PWA Kit de la version 2.7.x vers la version 3.0.0.

Nous avons ajouté un grand nombre de nouvelles fonctionnalités à PWA Kit v3, notamment :

⚛️ Requis :

Changement cassant getProps
Mises à jour majeures des bibliothèques, avec notamment la prise en charge de React 18, Node 18, Chakra 2 et plus encore.

🔨 Facultatif : Extensibilité des modèles — Réduisez considérablement l’empreinte du code de votre projet ainsi que le travail de développement, le coût de possession et les difficultés liées aux futures mises à jour. Pour en savoir plus, voir le guide Extensibilité des modèles !

🪝 Facultatif : Intégration des « hooks » @salesforce/commerce-sdk-react — Découple les appels API de l’implémentation d’un projet, permet aux appels API d’être mis à jour en tant que dépendances de bibliothèque npm, et apporte beaucoup de fonctionnalités intéressantes (notamment la gestion des états) via TanStack Query. Voir la documentation de Commerce SDK React pour commencer !

Les SDK PWA Kit ont été déplacés vers l’organisation NPM @salesforce. Pour effectuer une mise à jour vers la version 3, installez les nouveaux packages et remplacez toutes les instructions d’importation des packages suivants :

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

À partir de la version 3.0.0, PWA Kit introduit une nouvelle stratégie de récupération de données withReactQuery. Cette stratégie utilise la bibliothèque react-query et vous permet d’écrire des hooks React pour récupérer les données de manière isomorphe. Contrairement à ce qui se passe avec getProps, vous n’avez plus besoin de dupliquer la logique de récupération des données côté client et côté serveur. Dans cette version, par défaut, @salesforce/retail-react-app utilise @salesforce/commerce-sdk-react qui est alimenté par react-query.

Vous pouvez utiliser withReactQuery et withLegacyGetProps en même temps.
getProps et shouldGetProps ont été supprimées du modèle par défaut des pages de la Retail React App, mais ne sont pas obsolètes. Ces méthodes font l’objet d’un support à long terme.

Modifiez les dépendances dans package.json comme indiqué ci-dessous. Supprimez @chakra-ui/system de peerDependencies et incluez-le sous dependencies ou devDependencies.

Mettez à jour les moteurs dans package.json pour prendre en charge Node 18 et npm 9.

Réinstallez les dépendances de votre projet à l’aide de npm i.

Lors de la migration de la version 2.7.x vers la version 3.x, vous pouvez choisir d’utiliser ou non l’extensibilité des modèles. Pour en bénéficier, vous devez importer au moins un fichier depuis @salesforce/retail-react-app (ou un autre modèle extensible à l’avenir).

À partir de là, considérez le nombre de fichiers que vous avez modifiés à partir du projet original généré via npx pwa-kit-create-app@2.x. Certains clients possèdent un grand nombre (peut-être des centaines) de fichiers, mais même dans ce cas, un grand nombre d’entre eux peuvent rester inchangés. Ces fichiers non modifiés sont de bons candidats pour l’importation à partir de @salesforce/retail-react-app, mais nous vous recommandons de procéder avec précaution et progressivement. De nombreux fichiers dans @salesforce/retail-react-app sont similaires mais ont été modifiés par rapport à leur état précédent dans la v2.x de PWA Kit Retail React App. En particulier, l’intégration de @salesforce/commerce-sdk-react (les détails de la migration seront abordés plus tard) a entraîné la modification d’un grand nombre de fichiers en termes d’importations ainsi que de structure de fichiers. Elle a supprimé l’intégralité du répertoire commerce-api de l’application dès le départ, ce qui est en soi un changement important.

Lors de la migration d’un projet pour utiliser l’extensibilité des modèles, veuillez noter que la version 2.x des SDK de PWA Kit et les projets générés via npx pwa-kit-create-app@2.x n’ont pas de dépendance sur @salesforce/commerce-sdk-react, alors que le code plus récent @salesforce/retail-react-app@^1.x fait un usage intensif de cette bibliothèque, qui affecte et modifie de nombreux fichiers. Pour avoir une idée de l’ampleur des changements, vous pouvez comparer release-2.7.x → release-3.0.x dans ce diff Github https://github.com/SalesforceCommerceCloud/pwa-kit/compare/release-2.7.x...release-3.0.x?diff=unified#files_bucket et rechercher @salesforce/commerce-sdk-react pour prendre note de tous les ajouts qui débarquent dans cette importation.

Si votre application tente de partager du code avec la version 2.x (qui inclut le répertoire app/commerce-api), vous risquez d’ajouter du code inutile à votre paquet là où ce code existe (sous deux formes très différentes), à la fois dans le dossier commerce-api et dans le module npm @salesforce/commerce-sdk-react.

À compter de la version 3.0.0, PWA Kit utilise une stratégie de récupération différente withReactQuery. Cette stratégie exploite la bibliothèque react-query et active les requêtes dans la passe de rendu SSR. L’application @salesforce/retail-react-app utilise @salesforce/commerce-sdk-react qui est alimenté par react-query.

Pour que les hooks fonctionnent côté serveur, vous devez encapsuler votre composant AppConfig dans le nouveau composant d'ordre supérieur withReactQuery.

Dans le cadre de la migration vers ReactQuery en tant que stratégie de récupération par défaut @salesforce/retail-react-app@^1, une modification est nécessaire pour garantir que les appels getProps() existants continuent de fonctionner.

Lorsque vous effectuez les mises à jour des dépendances décrites ci-dessus, vous pouvez rencontrer des problèmes dans votre projet, liés aux bibliothèques ci-dessous. Dans les sections ci-dessous, nous proposons des solutions pour résoudre ces problèmes. Les particularités de votre projet varieront et les solutions proposées doivent être traitées comme des lignes directrices et non comme des règles absolues.

Pour la migration react-hook-form, consultez ici la documentation officielle du react-hook-form. Dans le projet PWA, deux emplacements nécessitent des modifications :

Déplacez l’objet errors du formulaire dans une couche supplémentaire de destruction pour les hooks de app/components/forms/ car l’objet errors a été déplacé dans l’objet formState.

Déplacez les propriétés de rendu de Controller dans la propriété field. La signature de rappel de Render renvoie un objet qui contient field et fieldState.

À compter de React 18, les avertissements d’hydratation apparaissent comme des erreurs au lieu d’avertissements comme auparavant dans React 17. Certaines mises à jour du code ont été nécessaires afin de supprimer ces erreurs potentielles qui empêchent la génération de l’application en cas d’erreurs d’hydratation. Il est essentiel de corriger ces erreurs pour garantir un rendu isomorphe de l’application. Cette erreur se produit en raison d’une incompatibilité entre le serveur et le client. Si un composant ou une page a un rendu conditionnel, vous devez vous assurer que l’hydratation est terminée avant de passer au rendu du code spécifique au client.

Dans votre projet, créez une fonction utilitaire pour déterminer si l’hydratation est terminée. Vous pouvez utiliser une variable intégrée fournie par window.__HYDRATING__ dans pwa-kit-react-sdk.

Si votre projet utilise des composants et des API de la bibliothèque @chakra-ui/react différents de ceux du modèle Retail React App, consultez la documentation officielle de la migration vers Chakra 2.

Pour prendre en charge Chakra 2, vous devez mettre à jour quelques fichiers dans les projets basés sur le modèle Retail React App :

Supprimez allowToggle dans le composant Accordion car vous ne pouvez pas utiliser allowMultiple et allowToggle en même temps dans Chakra 2.

Dans le composant Footer, l’importation de StylesProvider directement à partir de @chakra-ui/react est obsolète. Vous devrez le créer via createStylesContext('Footer').

Configurez userEvent avant d’appeler une action et attendez l’action dans les tests unitaires qui utilisent userEvent car dans la bibliothèque de tests React version 14.0.0, toutes les actions utilisateur sont asynchrones. Vous devrez donc appeler setup avant d’effectuer des actions utilisateur.

Exemple :

Pour en savoir plus, consultez la documentation officielle pour userEvent de testing-library.

Autre possibilité : pour éviter d’appeler setup() de manière répétitive dans de nombreux tests unitaires, vous pouvez configurer votre userEvent dans app/utils/test-util.js juste avant le rendu du composant de test, et le renvoyer avec les résultats du rendu afin que le test puisse effectuer les actions de l’utilisateur sans avoir à appeler setup().

Dans jest-setup, il existe une dépendance fictive qui peut générer une erreur indiquant que TextDecoder n’est pas défini dans jest-setup.js.. Ajoutez ce qui suit à jest-setup.js :

Lors de la migration à partir de la version 2.x des SDK du PWA Kit ou des projets générés via npx pwa-kit-create-app@2.x, le code @salesforce/commerce-sdk-react a été considérablement remanié afin de supprimer le répertoire app/commerce-api/. Au lieu que ces fichiers gèrent les requests API et agissent en tant que SDK, @salesforce/commerce-sdk-react remplace cette fonctionnalité. La version 3 des SDK est corrélée à la première version de @salesforce/retail-react-app@^1.x, car les SDK utilisent beaucoup cette bibliothèque.

L’implémentation de @salesforce/commerce-sdk-react modifie de nombreux fichiers dans la Retail React App. Pour avoir une idée de l’ampleur des modifications, comparez release-2.7.x à release-3.0.x dans ce diff GitHub et recherchez @salesforce/commerce-sdk-react. Dans le diff, prenez note de tous les ajouts qui incluent cette importation.