Déboguer des applications PWA Kit

Les bogues et les goulets d'étranglement des performances sont inévitables dans le développement d'une application Web. PWA Kit vous permettra d'aller au bout de ces problèmes grâce à une série d'outils et de techniques permettant d'examiner votre application de près.

Remplacez les espaces réservés de ce guide par des valeurs réelles. Les espaces réservés sont formatés ainsi : $PLACEHOLDER.

Avant de suivre les conseils plus ciblés de ce guide, essayez d'abord ces étapes de dépannage général :

• Vérifiez bien que vous exécutez une version prise en charge de Node (reportez-vous au guide Premiers pas) avant de démarrer votre serveur de développement local.
• Confirmez que votre serveur de développement fonctionne toujours et que le port n'est pas utilisé par un autre processus.
• Après une modification du code, confirmez que le message HTTP development server listening s'affiche dans le terminal avant d'actualiser votre navigateur.
• Cherchez les erreurs à la fois dans la console du navigateur et dans le terminal.
• Cherchez les réponses d'erreur réseau à l'aide des outils de développement de votre navigateur. (Dans les DevTools de Chrome, allez dans l'onglet Réseau).
• Pour vous aider à identifier les erreurs de syntaxe et les coquilles, lancez un formateur de code et un linter. Des fichiers de configuration sont fournis à la fois pour Prettier (formateur de code) et ESLint (linter) dans l'application Retail React App.
• Vérifiez les paramètres de l'antivirus et du pare-feu de votre ordinateur pour voir si quelque chose empêche votre code de s'exécuter ou bloque les requests réseau.
• Pour identifier et analyser les problèmes de performance, utilisez le profileur dans les DevTools de Chrome. Pour en savoir plus, consultez ce guide de Google : Analyser les performances d'exécution. Vous pouvez également installer l'extension React Developer Tools pour Chrome afin d'obtenir un autre onglet Profiler où vous pourrez consulter des informations similaires, mais au niveau des composants.

Il existe deux paramètres de requête spéciaux que vous pouvez ajouter à toute URL servie par votre application de commerce pour faciliter le débogage des problèmes liés au code côté serveur.

Le paramètre de requête __server_only arrête le processus d'hydratation afin que la page s'affiche dans votre navigateur exactement comme elle le fait après le rendu côté serveur. La possibilité d'afficher la version de la page rendue côté serveur aide à résoudre les problèmes non seulement de rendu côté serveur, mais aussi de référencement puisque les moteurs de recherche explorent cette version de la page.

Le paramètre de requête __pretty_print ajoute une mise en forme à l'objet __PRELOADED_STATE__ pour en améliorer la lisibilité. Cet objet fournit un instantané de l'état de votre application avant que l'hydratation ne commence ; il peut donc être utile, au débogage, de voir s'il contient les valeurs que vous attendez. Pour afficher le contenu de l'objet, chargez votre application, affichez la source de la page et recherchez __PRELOADED_STATE__.

L'objet __PRELOADED_STATE__ est inclus dans une balise <script> au sein de la source HTML de la page qui a été initialement demandée lorsque votre application commence à s'exécuter côté serveur. L'objet __PRELOADED_STATE__ contient les valeurs sérialisées renvoyées par la fonction getProps (notamment les versions de getProps qui sont jointes au composant _app et au composant page).

Par défaut, le serveur d'applications affiche les messages de la console dans le terminal, mais ne vous permet pas d'observer l'exécution du code. Cette limitation peut compliquer le débogage du code qui effectue le rendu des pages du côté serveur (ou sur votre machine locale).

Pour faciliter le débogage, vous pouvez démarrer votre serveur de développement local à l'aide d'une autre commande qui exécute un processus d'inspection dans Node, sur lequel un débogueur peut se greffer. (Pour en savoir plus, reportez-vous à la documentation de Node).

Vous pouvez joindre le débogueur inclus dans de nombreux navigateurs et éditeurs de texte populaires à ce processus d'inspection de Node. Voici les instructions pour Google Chrome et Visual Studio Code.

1. Ouvrez un terminal.
2. Accédez au répertoire de votre projet.
3. Lancez votre serveur de développement local à l'aide de npm run start:inspect.
4. Pour confirmer que le débogueur écoute, recherchez un message « Debugger listening » dans la sortie du terminal.
5. Ouvrez Chrome et entrez l'URL chrome://inspect.
6. Cliquez sur Open dedicated DevTools for Node (Ouvrir les DevTools dédiés pour Node).
7. DevTools s'ouvre dans une nouvelle fenêtre.
8. Pour confirmer que le débogueur est joint, cherchez un message « Debugger attached » dans la sortie du terminal.
9. Définissez des points d'arrêt, ajoutez des instructions debugger, etc.
10. Chargez une page de votre serveur de développement local dans Chrome.
11. Utilisez la fenêtre dédiée pour le débogage.

Vous pouvez maintenant suivre l'exécution de votre code côté serveur !

Pour en savoir plus sur le débogage avec des points d'arrêt dans DevTools, consultez ce guide de Google : Debug JavaScript.

1. Ouvrez les fichiers de votre projet dans Visual Studio Code.
2. À partir de la barre de menu, cliquez sur Terminal > New Terminal (Nouveau terminal).
3. Lancez votre serveur de développement local à l'aide de npm run start:inspect.
4. Ouvrez Command Palette. Raccourci pour Windows : Ctrl + Shift + P. Raccourci pour Mac Command + Shift + P.
5. Tapez la commande suivante : “Debug: Attach to Node Process.”
6. Une liste des processus Node s'affiche. Choisissez le premier de la liste.
7. Pour confirmer que le débogueur est joint, cherchez un message « Debugger attached » dans la sortie du terminal.
8. Définissez des points d'arrêt, ajoutez des instructions de débogage, etc.
9. Chargez une page de votre serveur de développement local dans votre navigateur Web.
10. Utilisez le débogueur intégré dans Visual Studio Code pour le débogage.

Vous pouvez maintenant suivre l'exécution de votre code côté serveur dans Visual Studio Code !

Il existe trois façons de déboguer le code déployé sur Managed Runtime (MRT) :

• Utilisez des mappages de source pour identifier l’endroit où les erreurs se sont produites.
• Journaux de queue pour déboguer les problèmes ou les erreurs en temps réel dans un environnement à faible volume.
• Pour un environnement de production, utilisez Log Center, qui offre de puissantes fonctionnalités de recherche et de rétention.

Utilisez des mappages de source pour identifier les erreurs côté serveur ou côté client. Les mappages de source fournissent une trace simple de la pile d’erreurs qui identifie l’endroit où une erreur s’est produite. Par exemple, la trace de pile identifie le fichier et le numéro de ligne où l’erreur s’est produite pour faciliter le dépannage.

Pour utiliser les mappages de source, vous devez créer votre site à l’aide de la version 3.4.x ou d’une version ultérieure de PWA Kit. Si vous disposez d’une version antérieure, mettez à niveau votre projet pour utiliser PWA Kit 3.4.x.

Deux choix s’offrent à vous pour activer les mappages de source : utiliser Runtime Admin ou l’API Managed Runtime.

Utiliser Runtime Admin

1. Connectez-vous à Runtime Admin.
2. Cliquez sur votre projet.
3. Cliquez sur un environnement.
4. Cliquez sur Environment Settings (Paramètres d’environnement).
5. Dans la section Advanced (Avancés), cliquez sur Edit (Modifier).
6. Activez Source Maps (Mappages de source).
7. En haut de la section Advanced, cliquez sur Update (Mettre à jour).
8. Attendez que le paquet finisse de se redéployer.

Utiliser l’API Managed Runtime

Appelez le point de terminaison d’API projects_target_partial_update et définissez enable_source_maps sur true. Cela configure la variable d’environnement Managed Runtime NODE_OPTIONS dans votre environnement avec --enable-source-maps et redéploie le paquet.

1. Lorsque vous créez votre projet, générez le fichier ssr.js.map en utilisant cette variable d’environnement local : PWA_KIT_SSR_SOURCE_MAP=true.

2. Déployez votre paquet sur Managed Runtime.

Une fois que vous avez activé et téléchargé des mappages de source, vous pouvez les afficher en utilisant les journaux de queue sur Managed Runtime.

L’utilisation de mappages de source peut entraîner des problèmes de performances. Par exemple, il y a une latence à chaque fois que l’on accède à error.stack. Donc, lorsque vous incluez console.error(e) dans votre code, cela peut ralentir votre site.

• Nouveaux environnements hors production : enable_source_maps est défini sur true.
• Nouveaux environnements de production : enable_source_maps est défini sur false. Ce comportement permet d’éviter les impacts potentiels sur les performances qui peuvent survenir lorsque la fonctionnalité de mappages de source est activée.
• Tous les environnements préexistants : enable_source_maps est défini sur false.

Si votre application est déployée sur Managed Runtime, le débogage à distance n’est pas pris en charge. Vous pouvez toutefois suivre les journaux de n’importe quel environnement Managed Runtime en temps réel pour vous aider à diagnostiquer les erreurs côté serveur.

Deux moyens vous permettent de suivre les journaux via la ligne de commande.

Si vous travaillez au sein d’un projet PWA Kit généré à partir de la version 2.4.1 ou ultérieure, vous pouvez :

• Afficher l’aide pour la commande logs : npm run tail-logs -- --help
• Suivre les journaux pour un projet et un environnement spécifiques : npm run tail-logs -- --environment $ENV_ID

Si vous travaillez en dehors d’un projet PWA Kit ou si vous avez un projet généré à partir d’une version antérieure à 2.4.1, vous pouvez utiliser npx pour :

• Afficher l’aide pour la commande logs : npx @salesforce/pwa-kit-dev tail-logs --help
• Suivre les journaux pour un identifiant d’environnement et un identifiant de projet spécifiques : npx @salesforce/pwa-kit-dev tail-logs --environment $ENV_ID --project $PROJ_ID

Concernant le suivi des journaux, gardez à l’esprit les contraintes suivantes :

• Chaque session de suivi de journal se terminera après 60 minutes.
• Chaque environnement peut prendre en charge jusqu’à 100 sessions de suivi de journal actives à la fois, pour l’ensemble des utilisateurs.
• Pour suivre les journaux, vous devez disposer des autorisations d’utilisateur développeur ou administrateur pour le projet Managed Runtime.

Utilisez Log Center pour résoudre les erreurs si vous avez créé un site à l’aide de PWA Kit ou si vous disposez d’une instance B2C Commerce. Log Center :

• Fournit un emplacement unique pour accéder aux journaux de Managed Runtime (MRT) et de votre instance B2C Commerce. Connectez ce qui se passe dans votre environnement MRT et ce qui se passe dans votre instance B2C Commerce.
• Permet de rechercher et de filtrer de nombreux journaux historiques. Vous pouvez obtenir plus d’informations sur ce qui s’est passé en production, afin d’enquêter et de résoudre les problèmes plus rapidement.

Ce guide se concentre sur le débogage pour les sites créés à l’aide de PWA Kit. Pour en savoir plus sur l’utilisation de Log Center avec votre instance B2C Commerce, reportez-vous à la section Log Center centralisé.

Pour accéder aux journaux MRT d’un environnement dans Log Center, vous devez d’abord :

1. Avoir le rôle Log Center User (Utilisateur Log Center) dans Account Manager. Pour vérifier, vérifiez votre rôle dans Account Manager. Si vous n’avez pas le rôle, demandez à votre administrateur Account Manager de vous accorder l’accès. Reportez-vous à la section Gestion d’Account Manager pour les utilisateurs de Salesforce B2C Commerce.

2. Configurez l’environnement comme suit :

   a. Marquez l’environnement comme environnement de production. Voir les détails et les limitations liés aux environnements de production.

   b. Sélectionnez une instance Commerce Cloud (B2C Commerce) pour vous connecter à l’environnement.

   c. Ajoutez un ou plusieurs identifiants de site à associer à l’environnement.

Une fois que vous avez rempli les prérequis, pour afficher les journaux MRT dans Log Center :

1. Lancez Log Center.
2. Sélectionnez une région.
3. Sélectionnez un realm. Si vous ne connaissez pas votre identifiant de realm, demandez-le à votre chargé de compte (AE) ou votre Customer Success Manager (CSM).
4. Cliquez sur Show filtered results (Afficher les résultats filtrés).
5. Cliquez sur Search > Current Search (Rechercher > Recherche actuelle).
6. Sous Service Type (Type de service), sélectionnez mrt.
7. Sous Host (Hôte), sélectionnez l’environnement de production dont vous souhaitez afficher les journaux MRT. Le format de l’hôte est $PROJECT.$ENVIRONMENT. Si vous disposez de plusieurs environnements de production MRT, vous pouvez voir plusieurs noms d’hôtes MRT.
8. Affichez les journaux MRT.

Pour en savoir plus sur les niveaux et les volumes de journalisation dans Log Center, reportez-vous à la section Configuration pour les administrateurs.