Fichiers de configuration

Les fichiers de configuration vous permettent de personnaliser de nombreux aspects du fonctionnement de votre application PWA Kit, notamment : l’accès aux API, la mise en forme des URL, la gestion de plusieurs sites, l’utilisation de proxy pour les requests et le rendu côté serveur.

Vous pouvez écrire un fichier de configuration dans JavaScript, YAML ou JSON au choix. Les extensions de fichier suivantes sont prises en charge : .js, .yml, .yaml et .json.

Lorsqu’un projet PWA Kit est créé avec le modèle Retail React App, il est fourni avec un seul fichier de configuration : app/config/default.js. Les objets de configuration qu’il exporte sont définis en fonction des options fournies à pwa-kit-create-app, mais vous pouvez mettre à jour votre configuration à tout moment. Des mises à jour sont souvent nécessaires après la génération initiale du projet pour qu’il reste synchronisé avec les modifications apportées aux instances B2C Commerce.

Afin de prendre en charge le rendu isomorphe, les valeurs de configuration sont sérialisées sur la page. N’insérez pas de secrets dans votre configuration !

Vous pouvez remplacer default.js ou le compléter par d’autres fichiers de configuration, car PWA Kit prend en charge des configurations propres à l’environnement. Nous les aborderons dans la suite de ce guide.

Commençons par examiner les objets et propriétés de configuration spécifiques disponibles dans default.js ou tout autre fichier de configuration.

La chaîne du projet qui associe votre application à Managed Runtime ne fait pas partie d’un fichier de configuration. Elle se trouve dans la propriété name en haut du fichier package.json situé à la racine de votre répertoire de projet. Après la génération initiale du projet, vous pouvez modifier la valeur de name pour qu’elle corresponde à l’identifiant de projet que vous voyez dans Runtime Admin.

Avant la version 1.5.0 de PWA Kit, ces paramètres se trouvaient dans app/api.config.js.

Pour configurer l’accès à B2C Commerce API et Open Commerce API (OCAPI), vous pouvez modifier l’objet app.commerceAPI exporté à partir du fichier de configuration.

Voici un snippet de code annoté avec des exemples de valeurs :

Pour configurer l’accès à Einstein API, vous pouvez modifier l’objet app.einsteinAPI.

Voici un autre fragment de code annoté avec des exemples de valeurs :

Pour en savoir plus sur la classe CommerceAPI qui utilise l'objet de configuration dans le snippet précédent, consultez notre guide d'architecture pour Retail React App.

Pour en savoir plus sur les tâches de configuration dans Account Manager et Business Manager afin d’activer l’accès aux API pour une instance B2C Commerce, consultez notre guide Configurer l’accès aux API.

Vous pouvez personnaliser le format des URL de la boutique dans l’objet app.url.

Par défaut, l’objet app.url est configuré avec les valeurs suivantes :

Avec ces paramètres par défaut, le site et le paramètre régional actuel s’affichent dans le chemin de l’URL.

Vous pouvez choisir comment le paramètre régional actuel apparaît (ou pas) dans l’URL en définissant url.locale sur l’une des valeurs suivantes :

path : le paramètre régional est inclus dans le chemin de l’URL. Exemple : /en-US/women/dress
query_param : le paramètre régional est inclus en tant que paramètre de requête. Exemple : /women/dress?locale=en-US
none : le paramètre régional n'est pas inclus dans l’URL. Exemple : /women/dress

url.showDefaults : cette valeur booléenne détermine si les valeurs du site ou du paramètre régional par défaut sont affichées dans l’URL. Elle est configurée par défaut sur false.

Nous extrayons les sites configurés pour votre application dans son propre fichier appelé config/sites.js. Ce fichier est importé dans chaque fichier de configuration et exporté dans l’objet app. La séparation des fichiers de cette manière vous permet de synchroniser plus facilement les sites pris en charge par votre application et les sites définis dans votre back-end Business Manager. (Vous pouvez définir vos sites directement dans le fichier de configuration si vous préférez.)

L’objet app contient également d’autres paramètres permettant de gérer plusieurs sites et leurs alias. Ces paramètres sont décrits en détail dans notre guide Plusieurs sites.

L’utilisation de proxy pour les requests est configurée dans le tableau ssrParameters.proxyConfigs. Ce dernier est abordé en détail dans notre guide Requests via proxy.

Avant la version 1.5.0 de PWA Kit, ces paramètres se trouvaient dans package.json.

Le tableau suivant met en évidence les options de configuration liées au rendu côté serveur. Ces options ne font pas partie de l’objet app et sont exprimées en tant que propriétés individuelles de l’objet exports principal.

Propriété	Description
`ssrParameters.ssrFunctionNodeVersion`	Chaîne qui détermine la version de Node à utiliser pour exécuter l’App Server. Valeurs autorisées : `16.x`.
`ssrEnabled`	Booléen qui active ou désactive la génération des fichiers nécessaires au rendu côté serveur. La configuration de cette valeur sur `false` est obsolète à compter du mois d'août 2021.
`ssrOnly`	Tableau d’expressions glob dans lequel `` est un caractère générique correspondant à un nombre indéterminé de caractères quelconques. Détermine quels fichiers sont disponibles exclusivement pour le système de rendu côté serveur et ne sont pas* disponibles via le chemin d’accès `/mobify/bundle/`. Valeurs par défaut pour un projet nouvellement généré : `['ssr.js', 'ssr.js.map', 'node_modules/*/.*']`
`ssrShared`	Tableau d’expressions glob dans lequel `` est un caractère générique correspondant à un nombre indéterminé de caractères quelconques. Détermine quels fichiers sont* disponibles pour le système de rendu côté serveur et disponibles via le chemin d’accès `/mobify/bundle/`. Paramètres par défaut pour un nouveau projet généré :

Vous pouvez inclure plusieurs fichiers de configuration dans le répertoire app/config/, notamment des fichiers de configuration pour des environnements spécifiques.

Les configurations spécifiques à un environnement peuvent améliorer l’efficacité et la flexibilité de vos déploiements. Par exemple, vous pouvez :

Déployer un même paquet sur plusieurs environnements Managed Runtime et faire en sorte que chaque environnement se connecte à une instance B2C Commerce différente.
Vous connecter à votre propre On-Demand Sandbox pendant le développement local, mais à des instances différentes lors du déploiement vers Managed Runtime.

Pour créer un fichier de configuration spécifique à un environnement, suivez les mêmes conventions que celles utilisées dans default.js, mais utilisez le nom de l’environnement cible comme nom de base du fichier. Utilisez l’un des formats de fichier pris en charge et l’extension de fichier correspondante. Exemples : production.js, staging.json.

Une application PWA Kit choisit le bon fichier de configuration à charger en recherchant app/config et en posant les questions suivantes, dans cet ordre :

Existe-t-il un fichier correspondant au nom de l’environnement en cours d’exécution sur Managed Runtime ?
S’il s’exécute localement, existe-t-il un fichier appelé local avec une extension de fichier prise en charge ?
Si aucun fichier de configuration n’a encore été trouvé, existe-t-il un fichier appelé default avec une extension de fichier prise en charge ?

Dès que la réponse à l’une de ces questions est positive, PWA Kit cesse ses recherches et charge le fichier en question.

Si deux fichiers ont le même nom de base mais des extensions de fichier différentes, l’extension de fichier ayant la priorité la plus élevée est choisie. Les extensions de fichier prises en charge suivent l’ordre suivant, de la priorité la plus élevée à la plus basse : .js, .yml, .yaml ou .json. Cela signifie qu’entre default.js et default.json, PWA Kit charge default.js, qui a la priorité la plus élevée.