Retail React App dans PWA Kit v2.x

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 pour l’application Retail React App dans Progressive Web App (PWA) Kit version 2.x :

• Décrit sa structure et son contenu
• Met en avant 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).

1.eslintignore                               Exclusion rules for ESLint
2.eslintrc.js                                Code style rules for ESLint
3.gitignore                                  Exclusion rules for git
4.prettierignore                             Exclusion rules for Prettier code formatting
5.prettierrc.yaml                            Code formatting rules for Prettier
6├── app/                                    Application code lives here
7    ├── assets/svg/                         SVG icon assets
8    ├── commerce-api/                       Commerce API client and hooks
9    ├── components/                         React components
10    │   ├── _app                            Root component
11    │   ├── _app-config                     Wrapper component for injecting custom code
12    │   └── _error                          Generic error component
13    │   └── ...
14    ├── constants.js                        Constants imported throughout the app
15    ├── contexts/                           React contexts
16    ├── hoc                                 Contains higher-order components
17    ├── hooks/                              React hooks
18    ├── main.jsx                            Client-side rendering entry point
19    ├── pages/                              Retail-oriented pages like home, PLP, and PDP
20    ├── partials/                           Partials imported throughout the app
21    ├── request-processor.js                Request processing functions (run at CDN edge)
22    ├── request-processor.test.js           Tests for request processing functions
23    ├── routes.jsx                          Maps request paths to route components
24    ├── routes.test.js                      Tests for mapping request paths to route components
25    └── ssr.js                              Server-side rendering entry point
26    ├── static/                             Static assets
27    │   └── manifest.json                   Manifest for PWA features like add to home screen
28    │   └── ...
29    ├── theme/                              Theme files for components
30    │   ├── components/
31    │   │   ├── base/                       Theme files for Chakra UI components
32    │   │   └── project/                    Theme files for custom components
33    │   ├── foundations/                    Frequently used theme values like colors and spacing
34    │   └── index.js
35    ├── translations/                       Translations for react-intl
36    ├── utils/                              Utilities imported throughout the app
37babel.config.js                             Transpilation rules for Babel
38cache-hash-config.json                      Cache breaking hash used by the CDN
39CHANGELOG.md                                Chronological list of changes to the template
40├── config/                                 Configuration files
41    ├── default.js                          Default configuration file
42    ├── mocks/                              Default configuration file with mock values for unit testing
43    └── sites.js                            Identifies sites configured in Business Manager. Includes localization details.
44jest-setup.js                               Unit testing setup for Jest
45jest.config.js                              Unit testing configuration for Jest
46LICENSE                                     Software licensing agreement
47node_modules/                               Package dependencies
48package-lock.json                           Package configuration lock file
49package.json                                Package configuration
50README.md                                   Basic documentation
51tests/                                      Unit tests
52worker/                                     Service worker

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 :

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 :

1npm run test

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 :

1npm run test:lighthouse

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.

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 config/default.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 :

1const MyPage = (props) => {
2  const {categories} = props
3  return <div>There are {categories.length} categories.</div>
4}
5
6MyPage.getProps = async ({api}) => {
7  categories = await api.shopperProducts.getCategory({
8    parameters: {id: categoryId, levels: 0}
9  })
10
11  return {categories}
12}

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

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.

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 :

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 côté serveur à partir du SDK React du 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.
• Consultez Référentiel GitHub pour plus d’informations sur les derniers fichiers de l’application Retail React App et d’autres paquets.

j

Premiers pas

Présentation de la boutique composable

Utiliser une boutique composable dans une implémentation hybride

Framework du PWA Kit

Fichiers de configuration

Requests via proxy

Retail React App

Rendu

Routage

Composants spéciaux

Gestion des états

Les compétences pour réussir

Ask the Community

Préparez-vous

Construire votre site

Habiliter votre équipe marchande

Tester, lancer et surveiller

Maintenir

Français

English

日本語

中文

繁體中文

Français

Deutsch

Italiano

한국어

Português

Español (México)