Mise à 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 :

🔨 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 casse-têtes liés aux futures mises à jour. Pour en savoir plus, voir le guide Extensibilité des modèles !

🪝 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 !

⚛️ Mises à jour majeures des bibliothèques de fournisseurs, avec notamment la prise en charge de React 18, Node 16/18, Chakra 2 et plus encore.

L’une des premières décisions à prendre lors de la migration de la version 2.7.x vers la version 3.x consiste à savoir si vous souhaitez tirer parti de l’extensibilité des modèles. Pour en bénéficier, vous devez importer au moins un fichier à partir de @salesforcef/retail-react-app (ou d’une autre application extensible). Vous pouvez choisir le nombre de fichiers que vous souhaitez hériter du modèle de base, mais vous devez vous engager à en importer au moins un.

À 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. Le répertoire commerce-api a été supprimé de Retail React App dans son intégralité.

À 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 de niveau supérieur withReactQuery.

Pour les projets qui tentent de passer à la v3 et qui continuent à utiliser getProps, encapsulez votre composant AppConfig dans le composant withLegacyGetProps.

Modifiez les dépendances dans package.json comme suit

Mettez à jour les moteurs dans package.json pour prendre en charge Node 18 et npm 9. Supprimez @chakra-ui/system des peerDependencies dans package.json puisque la version 2 est la dernière version majeure de Chakra.

Signalons un bogue dans nswapi, qui est une dépendance de jest-environment-jsdom incompatible avec Chakra 2. Elle génère une erreur ':disabled):not([disabled]' is not a valid selector sur certains des tests qui utilisent le composant Modal. Ce bogue n’affecte que les tests unitaires, pas l’exécution du navigateur. Nous utilisons npm 8 et ajoutons des remplacements (overrides) pour appliquer la version 2.2.2 du paquet nwsapi. La prise en charge de npm 7 est ainsi abandonnée.

Ajoutez une propriété overrides dans package.json pour forcer l’application de la version du paquet :

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

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 :

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

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

Ajoutez cette fonction partout où vous utilisez un rendu conditionnel. Plusieurs endroits peuvent permettre d’ajouter la fonction dans un projet PWA Kit :

Voir ici.

Si vous avez installé un plug-in de navigateur qui interfère avec le rendu DOM, vous risquez d’obtenir une erreur d’hydratation dans le pied de page. Par exemple, si vous utilisez l’extension LastPass, vous pouvez voir l’erreur sur le composant Subscribe dans le pied de page, car LastPass prend en charge le rendu du navigateur pour injecter une icône permettant d’activer la fenêtre contextuelle dans le champ. Si cette prise de contrôle se produit pendant le processus d’hydratation, l’erreur apparaît. Voici une astuce simple que vous pouvez utiliser sans devoir recourir à isHydrated() : changez l’ordre des composants de saisie comme ceci :

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 refactorisé 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 beaucoup de fichiers dans Retail React App. Pour avoir une idée de l’ampleur des changements, comparez release-2.7.x → release-3.0.x dans cediff GitHub et recherchez @salesforce/commerce-sdk-react. Dans le diff, notez tous les ajouts qui lancent cette importation.