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 :

Windows 10 avec le sous-système Windows pour Linux installé
macOS 10.13 ou supérieur
Ubuntu Linux 18.x ou supérieur

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.

Accédez à la page de téléchargement de Node 18.x pour télécharger le programme d’installation adapté à 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é.

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.

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

Ouvrez un terminal.
Exécutez node -v.
Vérifiez qu'il renvoie v18.16.1 (ou la dernière version 18.x).
Exécutez npm -v.
Vérifiez qu'il renvoie 9.5.1 (ou la dernière version incluse avec Node 18.x).

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

Ouvrez un terminal.
Exécutez npm install -g npm@9.5.1.
Exécutez à nouveau npm -v.
Vérifiez que la commande renvoie 9.5.1.

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.

Before you can use Managed Runtime and Runtime Admin, they must be enabled and you must request access to them. To enable Managed Runtime and Runtime Admin for your organization, reach out to your Salesforce account team. For access, ask your Commerce Cloud administrator to add either one of the following roles to your account using Account Manager: Managed Runtime User or Managed Runtime Admin.

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

Connectez-vous à Runtime Admin.
Cliquez sur New project (Nouveau projet).
Indiquez un nom pour le projet.
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 :

Ouvrez un terminal.
Accédez au répertoire du projet.
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 @v3.0.0 ou @v2.7.3. 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.

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.

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 configuration	Plus d'informations
Project ID dans Managed Runtime Admin	Administration 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 Commerce	Vous 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.dx.commercecloud.salesforce.com`
Identifiant client de Commerce API	Cet 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 Manager	Chaî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 Manager	Chaî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 Manager	Chaî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 Configurator	Consultez 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 :

Accédez à http://localhost:3000/

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.