Configurer votre environnement local

Ce guide explique comment configurer votre environnement local afin de développer avec PWA Kit.

Nous recommandons d'utiliser un système d'exploitation basé sur Unix pour le développement avec PWA Kit, tel que :

Utilisateurs Windows : voir les recommandations officielles de Microsoft pour les développeurs Node.

Vous devez installer les versions spécifiques de Node et de Node Package Manager (NPM) qui sont prises en charge par Managed Runtime.

Rendez-vous sur la page de téléchargement de Node 14.x pour télécharger le bon outil d'installation pour votre machine.

Utilisateurs Windows : téléchargez le fichier .msi qui correspond à votre processeur. Par exemple, si vous disposez d'un processeur Intel 64 bits, vous choisirez le programme d'installation x64.

Utilisateurs Mac : téléchargez le fichier .pkg.

Utilisateurs Apple Silicon : si vous n'avez pas déjà installé Rosetta, lancez softwareupdate --install-rosetta.

Utilisateurs Linux : téléchargez le fichier -linux qui correspond à votre processeur. Par exemple, si vous avez un processeur Intel 64 bits, vous choisirez le programme d'installation linux-x64 dans votre format d'archive préféré.

Exécuter le programme d’installation de Node

Maintenant que vous avez téléchargé l'outil d'installation approprié de Node, ouvrez-le et suivez les instructions d'installation.

Lorsque le programme d'installation vous le demande, acceptez l'option par défaut qui consiste à installer également le moteur d'exécution Node.js, installez Node Package Manager et ajoutez le moteur d'exécution Node.js à votre chemin.

Vérifier les versions de Node et NPM

Avant de continuer, vérifiez que les versions correctes de Node et NPM sont installées :

  1. Ouvrez un terminal.
  2. Exécutez node -v.
  3. Vérifiez qu'il renvoie v14.19.0 (ou la dernière version 14.x).
  4. Exécutez npm -v.
  5. Vérifiez qu'il renvoie 6.14.16 (ou la dernière version incluse avec Node 14.x).

Installer NPM manuellement

Si vous avez une autre version de NPM installée, vous pouvez installer la version 6.14.16 manuellement comme ceci :

  1. Ouvrez un terminal.
  2. Exécutez npm install -g npm@6.14.16.
  3. Exécutez à nouveau npm -v.
  4. Vérifiez que la commande renvoie 6.14.16.

Plusieurs versions de Node

Si vous voulez gérer plusieurs versions de Node sur Windows, nous vous recommandons Node Version Switcher ou Volta. Nous ne recommandons pas Node Version Manager (NVM) de Corey Butler pour Windows, car nous avons rencontré des problèmes avec ce logiciel lors de nos tests.

Pour les utilisateurs Mac et Linux, nous recommandons d'installer Node Version Manager.

Chaque boutique PWA Kit doit avoir un projet créé dans Runtime Admin pour gérer les déploiements.

Avant de pouvoir créer un projet et gérer des déploiements, Managed Runtime doit être activé pour votre organisation et vous devez demander l’accès à Runtime Admin. Si Managed Runtime n'a pas encore été activé, contactez l'équipe de votre compte Salesforce. Pour demander l'accès à Runtime Admin, contactez votre administrateur Commerce Cloud et demandez-lui d'ajouter l'un des rôles suivants à votre compte dans Account Manager : Managed Runtime User (Utilisateur Managed Runtime) ou Managed Runtime Admin (Administrateur Managed Runtime).

Si vous ou quelqu'un de votre équipe ne l'avez pas encore fait, voici comment créer un projet dans Runtime Admin :

  1. Connectez-vous à Runtime Admin.
  2. Cliquez sur New project (Nouveau projet).
  3. Indiquez un nom pour le projet.
  4. Cliquez sur Create Project (Créer le projet).

Notez l'identifiant du projet car vous en avez besoin pour générer des fichiers de projet pour le développement.

Lorsque vous créez un projet, le site n'est pas accessible sur le Web tant que l'infrastructure cloud nécessaire n'est pas déployée. Le processus de déploiement peut demander jusqu'à 40 minutes.

Pour en savoir plus sur ce que vous pouvez faire dans Runtime Admin, consultez notre guide Administration de Managed Runtime.

La plupart des développeurs PWA Kit commencent par cloner un référentiel contenant un ensemble de fichiers de projet généré précédemment. (Pour découvrir comment générer un nouveau projet, passez à la section suivante).

Après avoir cloné le référentiel de votre projet, vous devez installer les dépendances des paquets :

  1. Ouvrez un terminal.
  2. Accédez au répertoire du projet.
  3. Exécutez npm ci

Si vous avez déjà un projet PWA Kit existant et que vous avez suivi les instructions de la dernière section, vous pouvez passer directement à la section suivante. Sinon, vous devez générer un projet.

Pour générer un projet, ouvrez un terminal et exécutez la commande suivante. Remplacez ~/PLACEHOLDER-PROJECT-ID par un chemin qui inclut l'identifiant du projet provenant de Runtime Admin :

Dans la commande npx, vous pouvez remplacer @latest par une version spécifique de Retail React App, telle que @v2.0.0 ou @v1.5.2. Si vous ne spécifiez pas de version, vous pouvez obtenir des résultats inattendus en raison de la mise en cache des anciennes versions.

Préréglages de projet

Lorsque vous êtes invité à choisir un préréglage de projet, sélectionnez l'une des options suivantes :

  • retail-react-app-demo : utilisez le modèle de boutique Retail React App et utilisez la sandbox de démonstration pour le backend. Aucune autre configuration n'est requise.
  • retail-react-app : utilisez le modèle de boutique Retail React App et utilisez votre propre instance B2C Commerce pour le backend. Vous devez fournir des valeurs de configuration.

Valeurs de configuration

Si vous utilisez le préréglage retail-react-app, le script du générateur vous demande de fournir plusieurs valeurs de configuration. Ces valeurs de configuration associent votre nouveau projet PWA Kit à un projet correspondant dans l'outil Runtime Admin et à une instance B2C Commerce.

Le tableau suivant fournit plus d'informations sur chaque valeur de configuration de projet ainsi que l'emplacement où les trouver. Les valeurs de configuration sont également abordées plus en détail dans la documentation des API B2C Commerce. Voir Valeurs de configuration.

Valeur de configurationPlus d'informations
Project ID dans Managed Runtime AdminAdministration de Managed Runtime couvre la création de projet ainsi que la recherche d’un identifiant de projet existant.

Exemple : example-project
URL de votre instance B2C CommerceVous avez besoin d'une nouvelle instance B2C Commerce pour le développement ou les tests ? Voir Créer une On-Demand Sandbox.

Exemple : https://zzdc-001.sandbox.us01.dx.commercecloud.salesforce.com
Identifiant client de Commerce APICet identifiant ne se trouve plus dans Account Manager. Voir Générer un identifiant client pour l'accès aux API.

Exemple : 1adba44c-ee9b-41f9-b4bf-1bbc3dda1967
Identifiant du site dans Business ManagerChaîne utilisée pour identifier un site d'e-commerce précis.

Pour obtenir une liste des sites disponibles et de leur identifiant de site associé dans Business Manager, cliquez sur Administration > Sites > Gérer les sites.

Exemple : RefArch
Identifiant de l'organisation pour Commerce API dans Business ManagerChaîne utilisée pour identifier votre organisation pour l'accès à l'API en fonction du realm et de l'instance.

Pour trouver l'identifiant de l'organisation dans Business Manager, cliquez sur Administration > Développement du site > Paramètres de Salesforce Commerce API.

Exemple : f_ecom_zzdc_001
Shortcode de Commerce API dans Business ManagerChaîne de huit caractères attribuée à un realm à des fins de routage. Le shortcode s'applique à l'ensemble de votre environnement de realm, dans toutes les instances. (Le shortcode pour toutes les on-demand sandboxes est kv7kzm78).

Pour trouver votre shortcode dans Business Manager, cliquez sur Administration > Développement du site > Paramètres de Salesforce Commerce API.

Exemple : kv7kzm78
Identifiant client de l'API dans Einstein ConfiguratorConsultez la documentation sur Einstein API pour les développeurs Commerce Cloud et l'accès direct à Einstein Configurator.

Après avoir généré un projet, nous vous recommandons de valider (commit) les fichiers du projet généré dans un référentiel et de partager ce référentiel avec les développeurs de votre boutique.

Vous pouvez également modifier les valeurs de configuration d'un projet après qu'un projet a été généré. Pour en savoir plus, consultez la section Fichiers de configuration.

N'oubliez pas de mettre à jour la configuration à chaque fois que l'une de ces valeurs change, par exemple si vous personnalisez les fichiers du projet pour travailler avec une autre instance B2C Commerce.

Pour démarrer votre serveur Web pour le développement local, exécutez la commande suivante depuis le répertoire de votre projet :

Maintenant que le serveur de développement fonctionne, vous pouvez ouvrir un navigateur et prévisualiser votre boutique :

Vous pouvez arrêter le serveur de développement à tout moment en utilisant le raccourci clavier Control+C.

Pour prévisualiser une page rendue côté serveur, ajoutez la chaîne de requête ?__server_only à l'URL que vous souhaitez prévisualiser. Par exemple, vous pouvez tester la version rendue côté serveur de www.example.com grâce à l'URL www.example.com?__server_only.

  • Après avoir cloné un projet existant et exécuté npm ci ou généré un nouveau projet, il peut s'écouler quelques minutes avant de constater une quelconque activité dans le terminal, alors n'annulez pas le processus avant qu'il soit terminé. De même, les logiciels antivirus (en particulier sous Windows) peuvent rallonger la durée des installations.

  • Si vous obtenez une réponse d'erreur HTTP 401 du point de terminaison authorize, il y a un problème de configuration avec le SLAS (Shopper Login and API Access Service). Pour corriger votre configuration de SLAS, consultez les instructions de la section Configurer l’accès aux API.

Maintenant que votre environnement de développement local est en place, l’étape suivante consiste à pousser un paquet de code vers Managed Runtime et à le déployer à l’aide de Runtime Admin. Une fois que vous pouvez accéder à Runtime Admin, vous êtes prêt à passer au guide suivant de la série Premiers pas : Envoyer en Push et déployer des paquets.