Routage

Lorsqu’un utilisateur lance une request sur le domaine de votre boutique en ligne, elle est gérée par un gestionnaire Express.js appelé render, défini dans pwa-kit-react-sdk/ssr/server/react-rendering. Le gestionnaire choisit un composant à afficher (rendre) en réponse. Ce type de composant s'appelle une route. Les routes qui sont disponibles pour le rendu sont définies dans un tableau d’objets appelés routes dans app/routes.jsx.

Le tableau des routes suit la forme de configuration route, telle que définie par React Router. Chaque objet du tableau routes peut avoir les propriétés suivantes :

Clé	Type	Description	Docs de référence
path	Une chaîne de style Express, un tableau de chaînes ou une expression régulière	Le chemin qui est comparé au chemin de la request entrante pour une correspondance potentielle	React Router API → Route component → path
component	Fonction (importée dans `routes.jsx`)	Composant à rendre (afficher) si le chemin correspond à la request	React Router API → Route component → component
exact	Booléen	Détermine si le chemin doit correspondre exactement ou non	React Router API → Route component → exact

Un projet récemment généré comprend déjà des objets dans le tableau routes pour de nombreuses pages d'e-commerce standard, telles que la page d'accueil, la page de liste des produits et la page des détails des produits.

Mais comment votre application React choisit-elle le bon composant à rendre pour une request donnée ? Nous utilisons la bibliothèque React Router pour rechercher séquentiellement les objets de configuration de route dans le tableau routes jusqu'à ce qu'elle trouve une chaîne path correspondant au chemin demandé.

React Router vous offre de nombreuses options pour construire vos chaînes path. Vous pouvez spécifier plusieurs chemins pour le même composant et utiliser des expressions régulières pour faire correspondre les chemins qui suivent un schéma.

React Router est également utilisé dans l'ensemble de Retail React App pour implémenter la navigation. Tous les liens hypertextes utilisent par exemple le composant Link de React Router. React Router propose d'autres composants qui vous permettent d'accéder à l'historique du navigateur, aux paramètres de requête, et plus encore.

Pour en savoir plus sur l'utilisation de React Router, consultez la documentation officielle. (Tenez-vous-en à la documentation de la version 5, car les autres versions utilisent un système de correspondance des schémas différent).

Chaque composant spécifié dans le tableau routes est automatiquement amélioré par la fonction routeComponent, un composant d'ordre supérieur du SDK React de PWA Kit. La classe de base qui est utilisée pour construire routeComponent définit plusieurs méthodes statiques, dont deux importantes que les développeurs de boutique peuvent personnaliser : getProps et shouldGetProps.

La méthode getProps est utilisée pour fournir des données récupérées à partir de requests API à routeComponent à l’aide de l’objet props.

Lorsque routeComponent améliore un composant du tableau routes, il recherche dans les propriétés du composant une fonction nommée getProps. Si vous y définissez une fonction, elle est exposée comme une méthode du composant amélioré. Il n’est pas nécessaire de définir la fonction pour chaque composant du tableau routes mais seulement pour ceux dont vous récupérez les données avant d’en effectuer le rendu.

La fonction getProps que vous définissez est censée renvoyer un paramètre promise. Au moment de tenir cette « promesse », sa valeur résolue est transmise au composant amélioré par le biais de l’objet props quand le composant est rendu.

Lorsqu'un composant du tableau routes est rendu, la méthode getProps du composant est fournie avec un seul objet JavaScript. Cet objet possède les propriétés suivantes, en fonction du contexte de rendu :

Clé	Type	Description	Disponibilité	Plus d’informations
`params`	Objet	Contient des propriétés d’objet qui correspondent aux paramètres de route nommés dans une chaîne de route de style Express. Exemple : Si vous avez une route `/user/:name`, alors la valeur de `:name` dans le chemin de la request est disponible en tant que params.name. Valeur par défaut : `{}`.	Tant du côté client que du côté serveur	API Express → Request → req.params
`req`	Objet	Une version de l’objet de request de Node améliorée par Express. Représente la request HTTP avec des propriétés pour la chaîne de requête, les paramètres, le corps, les en-têtes HTTP, et plus encore.	Côté serveur uniquement	API Express → Request
`res`	Objet	Représente la réponse HTTP qu’une application Express envoie lorsqu’elle reçoit une request HTTP.	Côté serveur uniquement	API Express → Response
`location`	Chaîne	L’URL de la request.	Côté client et côté serveur	Ne fait pas partie de l'API Express

À partir de la version 3.0.0, nous avons introduit une nouvelle stratégie de récupération de données appelée withReactQuery que vous pouvez utiliser à la place de getProps.
Vous pouvez utiliser withReactQuery et withLegacyGetProps en même temps.
getProps et shouldGetProps ont été supprimées du modèle par défaut des pages de la Retail React App, mais ne sont pas obsolètes. Ces méthodes font l’objet d’un support à long terme.

Reportez-vous à Mettre à jour vers la version 3.

Pour gérer les erreurs dans une fonction getProps, vous avez deux possibilités.

La première consiste à lever un objet HTTPError, qui peut être importé de pwa-kit-react-sdk/ssr/universal/errors. Si vous levez une HTTPError, un composant Error dédié est rendu.

La deuxième possibilité consiste à utiliser des props pour informer le composant rendu de l'erreur afin qu'elle puisse être utilisée dans une logique de gestion des erreurs personnalisée.

Voici un exemple qui utilise ces deux approches de gestion des erreurs :

L'objet renvoyé par getProps est sérialisé et intégré dans le HTML rendu via un objet appelé __PRELOADED_STATE__ dans la source de la page.

Pour limiter la taille du HTML rendu, soyez sélectif sur les données à renvoyer dans getProps. Par exemple, évitez si possible de renvoyer l'intégralité de la réponse d'une request API.

Pour prévisualiser la version de la page rendue côté serveur dans votre navigateur, ajoutez ?__server_only à l'URL. Ce paramètre de requête arrête le processus d'hydratation afin que le navigateur ne prenne pas le relais du rendu, et laisse la page inchangée après le rendu côté serveur. Pour voir une version mise en forme par Prettier de l'objet __PRELOADED_STATE__, ajoutez ?__server_only&__pretty_print à la chaîne de requête.

Si les utilisateurs naviguent vers des pages ultérieures pendant le rendu côté client, la page est rendue immédiatement. Étant donné que le rendu peut avoir lieu alors que getProps est toujours en train de récupérer des données, écrivez toujours du code conditionnel dans vos composants pour gérer les props non définis. N'oubliez pas non plus de rendre un composant de substitution (comme Skeleton de Chakra UI) tant que les props ne sont pas définis.

Côté client, la méthode render de votre composant est appelée avant et après la résolution de getProps. Utilisez la propriété isLoading passée à votre composant pour décider si vous souhaitez afficher ou non un écran de chargement.

Lorsque vous effectuez plusieurs requests HTTP dans getProps, essayez de les lancer en parallèle. Si ce n’est pas possible, envisagez de les déplacer vers le rendu côté client.

Si vous souhaitez uniquement récupérer des données du côté client, utilisez des hooks React dans votre composant au lieu de getProps.

Si vous voulez exécuter le même code pour toutes les routes, vous pouvez définir une fonction getProps appartenant au composant App, qui est l’un des composants spéciaux. Les composants spéciaux sont utilisés pour ajouter des fonctionnalités partagées entre plusieurs routes. Pour en savoir plus sur le composant App et d’autres composants spéciaux, consultez notre guide Composants spéciaux.

La méthode shouldGetProps contrôle le moment où la méthode getProps doit être appelée. Pendant le rendu côté serveur, shouldGetProps n'est appelée qu'une seule fois. Pendant le rendu côté client, elle est appelée à chaque fois que la méthode componentDidUpdate du cycle de vie React est appelée.

Par défaut, getProps appelle getProps à chaque fois que la valeur de location.pathname change. Vous pouvez remplacer le comportement par défaut pour chaque composant du tableau routes en définissant votre propre fonction appelée shouldGetProps en tant que propriété du composant. Vous pouvez personnaliser shouldGetProps pour inspecter la request et n'appeler getProps que pour certaines requests.

Approfondissez votre compréhension du routage en examinant le code source. Voici quelques fichiers essentiels à consulter dans l'application Retail React App :

app/routes.jsx : démontre la syntaxe de style Express pour la correspondance des chemins, y compris les paramètres de route nommés.
app/pages/product-detail/index.jsx : ce composant proposé à titre d'exemple pour les pages de détails de produits comprend des fonctions personnalisées pour getProps et shouldGetProps.
app/components/_app_config/index.jsx : comprend un code de configuration étendu et une fonction getProps à l'échelle de l'application.

Pour une autre approche de routage, consultez Résolution d’URL.

En parcourant la documentation de PWA Kit, ne passez pas à côté du guide d'architecture pour l'application Retail React App.