Retail React App

L’application Retail React App est un exemple d’ensemble de code et d’outils conçu pour vous donner une longueur d’avance lors de la création de votre boutique sur des API et de son hébergement sur Managed Runtime. Ce guide d'architecture décrit la structure et le contenu de Retail React App et met en évidence sa base flexible et open source.

Tous les projets PWA Kit commencent avec le même ensemble de fichiers. Au début d'un projet, ces fichiers sont générés par l'exécution d'un script. (Ce processus est détaillé dans le guide Premiers pas.)

Pour vous faire une idée du fonctionnement de Retail React App, commencez par explorer sa structure de fichiers. Voici une liste de tous les fichiers et répertoires d'un projet récemment généré ainsi qu'une brève description de chacun d'eux. (Les technologies mentionnées dans les descriptions sont traitées plus en détail dans la suite de ce guide).

Pour automatiser les tâches de développement de routine, Retail React App comprend plusieurs scripts. Utilisez la commande npm run <SCRIPT_NAME> pour les exécuter à partir du terminal.

Voici une liste complète de tous les scripts inclus avec une description de chacun d'eux :

Nom	Description
`analyze-build`	Génère le projet en mode production et crée deux rapports webpack-bundle-analyzer. Utilisez les rapports pour surveiller la taille de votre paquet de code.
`compile-messages`	Compiler tous les messages localisés au format AST.
`extract-messages`	Extraire automatiquement les messages du paramètre régional par défaut de vos composants React.
`format`	Mettre le code en forme à l'aide de Prettier.
`lint`	Détecter un style de code incohérent à l'aide d'ESlint.
`lint:fix`	Corriger automatiquement les erreurs ESlint.
`prod:build`	Générer le projet en mode production.
`push`	Pousser le paquet de code (artefacts de build de production) vers Managed Runtime.
`save-credentials`	Enregistrer localement les informations d'identification de Runtime Admin (pour la commande push).
`start`	Démarrer le serveur SSR.
`start:inspect`	Démarrer le serveur SSR en utilisant l'inspecteur Node.js.
`start:pseudolocale`	Démarrer le serveur SSR avec un pseudo-paramètre régional.
`test`	Exécuter des tests unitaires en utilisant Jest.
`test:lighthouse`	Exécuter les tests de Lighthouse.
`test:max-file-size`	Exécuter un test de taille du paquet.

Votre projet est livré avec deux exemples de suites de tests pour l'assurance qualité : des tests unitaires créés avec Jest et React Testing Library.

Les tests unitaires sont inclus avec chacun des composants de la page dans leurs répertoires respectifs.

Pour lancer les tests unitaires, exécutez la commande suivante dans votre terminal :

Pour en savoir plus sur le test de votre boutique, examinez le code source des suites de tests fournies en exemple et explorez la documentation de Jest et React Testing Library.

Dès le départ, Retail React App obtient d'excellents résultats en termes de performances, comme le montre la suite de tests Lighthouse de Google. Nous facilitons le suivi de vos scores Lighthouse tout au long du développement à l'aide du script suivant :

Le script exécute Lighthouse trois fois sur votre boutique et télécharge les scores médians pour chaque catégorie dans Google. Google utilise ensuite ces scores pour générer un rapport. Un lien vers le rapport est affiché par le script avant qu'il ne se termine.

Pour utiliser les API Salesforce afin d’accéder aux données des acheteurs, un administrateur doit effectuer les tâches décrites dans Configurer l’accès aux API.

Les données des acheteurs dans Retail React App sont accessibles via une classe appelée CommerceAPI qui est générée au-dessus du client commerce-sdk-isomorphic. Vous pouvez personnaliser la classe CommerceAPI dans app/commerce-api/index.js et la configurer dans app/api.config.js.

La classe CommerceAPI est automatiquement injectée dans la méthode getProps de chaque page. Par exemple, vous pouvez accéder au wrapper API à partir d'un composant de page comme ceci :

Le wrapper CommerceAPI utilise actuellement Commerce API pour les produits, les promotions, les chèques-cadeaux et la recherche. Chacune de ces fonctionnalités est fournie avec son propre ensemble de points de terminaison, qui sont documentés séparément dans la référence B2C Commerce API.

Pour autoriser les requests API au nom des acheteurs et des invités enregistrés, la classe CommerceAPI s'appuie sur une Salesforce Commerce API appelée Shopper Login and API Access Service (SLAS).

Pour les paniers et les commandes, la classe CommerceAPI utilise également l'Open Commerce API (OCAPI).

Les instructions relatives à la configuration de Salesforce Commerce API (y compris SLAS) et de l’OCAPI sont traitées dans la section Configurer l’accès aux API.

La bibliothèque de composants Chakra UI est une technologie nouvelle, mais prête à être mise en production, que nous sommes ravis d'utiliser dans Retail React App. Elle comprend plus de 50 composants d'interface utilisateur, tous dotés d'une excellente accessibilité et ergonomie. Les composants peuvent être personnalisés avec des props de style ou à l'aide d'objets JavaScript pour des options de style plus avancé (CSS-in-JS). Tous les composants Chakra sont fournis avec des styles de base bien conçus qui peuvent être remplacés par un système de thématisation.

Le système Chakra Theming s’appuie sur la spécification du thème styled-system. Vous pouvez personnaliser l'apparence et l'ergonomie de vos composants en fonction de votre marque en mettant à jour les valeurs du répertoire app/theme.

La thématisation est disponible pour la plupart des composants réutilisables dans, app/components mais elle n'est pas disponible pour les pages comme la page de détails du produit ou la page de liste des produits. Pour changer le style de ces pages, modifiez les styles en ligne dans le code source de leurs composants de page respectifs dans app/pages.

Pour inclure des icônes SVG personnalisées dans le projet, ajoutez-les au répertoire app/assets/svg, importez-les dans app/components/icons/index.js et exportez le composant React icon comme suit : export const MyCustomIcon = icon('my-custom-icon').

Les icônes SVG importées sont regroupées dans un sprite SVG au moment de la build, et le sprite est inclus dans le rendu HTML côté serveur.

Le SDK React de PWA Kit est une bibliothèque qui prend en charge le pipeline de rendu isomorphe pour les boutiques PWA Kit. Il contient de nombreuses classes, fonctions et composants essentiels qui permettent le fonctionnement de Retail React App. Par exemple, la fonction render() dans app/ssr.js, qui lance l'ensemble du processus de rendu et de routage est importée du SDK.

Le SDK fait abstraction de certains détails de l'implémentation du rendu côté serveur, de la mise en cache et de l'utilisation de proxy, et vous offre de nombreuses possibilités de personnaliser leur fonctionnement. Il fournit également des utilitaires et des outils à usage général permettant de maintenir un ensemble unique de code pouvant être rendu à la fois côté client et côté serveur.

Salesforce maintient le SDK sous la forme d'un paquet npm distinct de Retail React App afin de pouvoir y apporter plus facilement des améliorations.

Le SDK React de PWA Kit et l’ensemble de l’application Retail React App sont des projets open source disponibles sur GitHub. Nous accueillons avec plaisir les contributions de la communauté Commerce Cloud !

Les technologies open source énumérées dans cette section sont celles qui sont utilisées le plus fréquemment par l'application Retail React App. Elles sont également les plus difficiles à remplacer par d'autres solutions ; nous les avons donc sélectionnées non seulement pour leurs caractéristiques de performance, mais aussi pour leur réputation. Chacune d'entre elles est activement maintenue, hautement personnalisable, bien documentée et largement utilisée.

Voici un bref aperçu de chacune de ces technologies fondamentales, dont beaucoup vous sont probablement déjà familières :

Babel compile votre code JavaScript pour le rendre compatible avec un large éventail de navigateurs et d'environnements Node.js. Il transforme la syntaxe avancée du langage et émule toutes les fonctionnalités qui manquent à l'environnement.

Express est un framework de serveur Web open source populaire, écrit en JavaScript et exécuté dans l'environnement d'exécution Node.js. Il gère les requests HTTP pour les routes que vous définissez comme les points d'entrée de votre boutique.

Express vous permet de configurer les paramètres courants des serveurs Web, tels que le port de connexion et l'emplacement des modèles de renvoi de la réponse. Il permet également d'ajouter un middleware de traitement supplémentaire des requests à n'importe quel point du pipeline de traitement des requests.

Tout le code côté serveur d'une application PWA Kit est exécuté au-dessus de Node.js, un environnement d'exécution open source pour JavaScript. L'environnement d'exécution omet les API JavaScript spécifiques au navigateur et inclut ses propres API pour accéder aux fonctionnalités du système d'exploitation hôte (comme le système de fichiers) en mode multiplateforme.

Node.js utilise une architecture non bloquante ou asynchrone, idéale pour créer des boutiques hautement évolutives et riches en données.

React est un framework développé par Facebook pour créer des applications d'une seule page avec des interfaces utilisateur rapides, fluides et immersives.

Dans une application React, l'interface utilisateur est construite avec des composants discrets, généralement organisés dans des hiérarchies complexes. Dans une application React bien conçue, chaque composant n'est responsable que d'une seule tâche, et souvent, cette tâche consiste simplement à contenir d'autres composants.

La hiérarchie des composants dans Retail React App est conçue pour être extensible. Vous pouvez créer à partir des composants inclus ou les remplacer par de nouveaux composants.

Paquets liés à React :

Nom	Description
Loadable Components	Accélère les performances grâce au fractionnement du code des plus gros paquets.
ReactDOM	Fournit des méthodes spécifiques à DOM qui peuvent être utilisées au niveau supérieur de votre application.
ReactDOMServer	Fournit la méthode renderToString() qui pré-rend le HTML côté serveur.
React Helmet	Vous aide à gérer les modifications de la balise `head` du document.
React Router	Mappe les chemins URL vers les composants React. Les chemins peuvent être exprimés sous la forme de schémas qui sont mappés du plus spécifique au moins spécifique.

Webpack fusionne votre code dans un ou plusieurs paquets. Ces paquets sont déployés dans Managed Runtime et finalement chargés dans le navigateur dans le cadre du processus d’hydratation.

L'application Retail React App importe des configurations Webpack prêtes à l'emploi pour le côté client et le côté serveur à partir du SDK React de PWA Kit. Dans la plupart des cas, vous n'avez pas besoin de modifier ces configurations, mais le cas échéant, vous pouvez étendre la configuration de Webpack dans webpack.config.js.

Maintenant que vous connaissez la structure et le contenu de Retail React App, il est temps d'approfondir le sujet ! Commencez par explorer le code source, notamment les composants d'e-commerce qui se trouvent dans app/pages.