Routing

Quando un utente effettua una richiesta nel dominio dello storefront, essa viene gestita da un handler Express.js denominato render definito in pwa-kit-react-sdk/ssr/server/react-rendering. L'handler sceglie un componente da renderizzare in risposta. Questo tipo di componente è definito route. Le route disponibili per il rendering vengono definite in una matrice di oggetti chiamata routes in app/routes.jsx.

La matrice routes segue la forma di configurazione route definita da React Router. Ogni oggetto della matrice routes può avere le seguenti proprietà:

Chiave	Tipo	Descrizione	Documentazione di riferimento
path	Stringa di tipo Express, matrice di stringhe o espressione regolare	Il percorso che viene confrontato con quello della richiesta in ingresso per una potenziale corrispondenza	React Router API → componente Route → path
component	Funzione (importata in `routes.jsx`)	Componente da renderizzare se il percorso corrisponde alla richiesta	React Router API → componente Route → component
exact	Booleano	Determina se il percorso deve essere o meno una corrispondenza esatta	React Router API → componente Route → exact

Un progetto appena generato include già oggetti nella matrice routes per molte pagine di e-commerce standard, come la pagina principale, la pagina di elenco prodotti (PLP) e la pagina di dettagli prodotto (PDP).

In che modo l'app React sceglie il componente appropriato da renderizzare per una determinata richiesta? Mediante la libreria React Router viene effettuata una ricerca sequenziale tra gli oggetti di configurazione route nella matrice routes finché non viene individuata una stringa path che corrisponde al percorso richiesto.

React Router offre numerose opzioni per la costruzione delle stringhe path. È possibile specificare più di un percorso per lo stesso componente e utilizzare espressioni regolari per abbinare i percorsi che seguono un determinato modello.

Inoltre, React Router viene utilizzato ovunque in Retail React App per implementare la navigazione. Ad esempio, tutti i collegamenti ipertestuali utilizzano il componente Link di React Router. React Router offre altri componenti che danno accesso alla cronologia del browser, ai parametri di query e altro ancora.

Per ulteriori informazioni sull'uso di React Router, consultare la documentazione ufficiale. (Attenersi alla documentazione della versione 5 perché le altre versioni utilizzano un sistema di abbinamento con modello diverso.)

Ogni componente specificato nella matrice routes viene automaticamente ottimizzato dalla funzione routeComponent, un higher-order component (HOC) (componente di ordine superiore) di PWA Kit React SDK. La classe base utilizzata per costruire routeComponent definisce diversi metodi statici, inclusi getProps e shouldGetProps, due importanti metodi che possono essere personalizzati dagli sviluppatori di storefront.

Il metodo getProps viene utilizzato per fornire dati recuperati dalle richieste API a routeComponent tramite l'oggetto props.

Quando ottimizza un componente dalla matrice routes, routeComponent cerca all'interno delle proprietà del componente una funzione denominata getProps. Se si definisce una funzione in questo punto, essa verrà esposta come metodo del componente ottimizzato. Non è necessario definire la funzione per tutti i componenti della matrice routes, ma solo per quelli per i quali vengono recuperati i dati prima del rendering.

La funzione getProps che viene definita dovrebbe restituire una promessa (oggetto Promise). Quando la promessa è in stato "settled" (adempiuta), il suo valore risolto viene trasmesso al componente ottimizzato attraverso l'oggetto props quando il componente viene renderizzato.

Quando un componente della matrice routes viene renderizzato, il relativo metodo getProps riceve un singolo oggetto JavaScript. Questo oggetto ha le seguenti proprietà a seconda del contesto di rendering:

Chiave	Tipo	Descrizione	Disponibilità	Ulteriori informazioni
`params`	Oggetto	Contiene proprietà oggetto che corrispondono ai parametri route denominati in una stringa route di tipo Express. Esempio: Se si dispone della route `/user/:name`, il valore di `:name` nel percorso della richiesta è disponibile come params.name. Valore predefinito: `{}`.	Lato client e lato server	Express API → Request → req.params
`req`	Oggetto	Una versione dell'oggetto richiesta di Node ottimizzato da Express. Rappresenta la richiesta HTTP, con proprietà per stringa di query, parametri, corpo, intestazioni HTTP e altro.	Solo lato server	Express API → Request
`res`	Oggetto	Rappresenta la risposta HTTP che un'app Express invia quando riceve una richiesta HTTP.	Solo lato server	Express API → Response
`location`	Stringa	L'URL della richiesta.	Lato client e lato server	Non appartenente a Express API

A partire dalla versione 3.0.0 è stata introdotta una nuova strategia di recupero dei dati denominata withReactQuery che è possibile utilizzare al posto di getProps.
È possibile utilizzare contemporaneamente sia withReactQuery sia withLegacyGetProps.
getProps e shouldGetProps sono state rimosse dal modello predefinito delle pagine di Retail React App, ma non sono deprecate. Il supporto a lungo termine per questi non viene interrotto.

Vedere Upgrade a v3.

Gli errori in una funzione getProps possono essere gestiti in due modi.

Il primo consiste nel restituire un oggetto HTTPError, che può essere importato da pwa-kit-react-sdk/ssr/universal/errors. Quando si restituisce un oggetto HTTPError, viene renderizzato un componente Error dedicato.

Il secondo prevede l'uso delle prop per informare dell'errore il componente renderizzato, in modo che possa essere utilizzato nella logica di gestione errori personalizzata.

Ecco un esempio in cui vengono utilizzati entrambi gli approcci:

L'oggetto restituito da getProps viene serializzato e incorporato nell'HTML renderizzato tramite un oggetto denominato __PRELOADED_STATE__ nell'origine della pagina.

Per mantenere contenute le dimensioni dell'HTML renderizzato, adottare un approccio selettivo riguardo ai dati da restituire in getProps. Ad esempio, evitare se possibile di restituire l'intera risposta da una richiesta API.

Per visualizzare in anteprima nel browser la versione della pagina renderizzata sul lato server, aggiungere ?__server_only all'URL. Questo parametro di query interrompe il processo di hydration, evitando l'intervento del browser nell'esecuzione del rendering e lasciando la pagina invariata dopo il rendering di lato server. Per visualizzare una versione pretty-print dell'oggetto __PRELOADED_STATE__, aggiungere ?__server_only&__pretty_print alla stringa di query.

Quando gli utenti passano alle pagine successive durante il rendering di lato client, la pagina viene renderizzata immediatamente. Poiché il rendering può avvenire mentre getProps sta ancora recuperando i dati, è necessario scrivere sempre codice condizionale nei componenti per gestire le prop indefinite. Inoltre, ricordarsi di renderizzare un componente segnaposto (come Skeleton di Chakra UI) mentre le prop non sono definite.

Sul lato client, il metodo render del componente viene richiamato prima e dopo la risoluzione di getProps. Utilizzare la prop isLoading passata al componente per decidere se renderizzare o meno una schermata di caricamento.

Quando si effettuano più richieste HTTP in getProps, cercare di effettuarle in parallelo. Se non è possibile effettuarle in parallelo, trasferirle al rendering di lato client.

Se si desidera recuperare i dati solo sul lato client, utilizzare gli hook React nel componente anziché getProps.

Se si desidera eseguire lo stesso codice per tutte le route, è possibile definire una funzione getProps appartenente al componente App, che è uno dei componenti speciali. I componenti speciali vengono utilizzati per aggiungere funzionalità condivise tra più route. Per ulteriori informazioni sul componente App e su altri componenti speciali, consultare la guida Componenti speciali.

Il metodo shouldGetProps determina quando richiamare il metodo getProps. Durante il rendering di lato server, shouldGetProps viene richiamato una sola volta. Durante il rendering di lato client, viene richiamato ogni volta che viene richiamato il metodo di ciclo di vita React componentDidUpdate.

Per impostazione predefinita, getProps richiama getProps ogni volta che il valore di location.pathname cambia. È possibile ignorare il comportamento predefinito per ogni componente nella matrice routes definendo la propria funzione denominata shouldGetProps come proprietà del componente stesso. È possibile personalizzare shouldGetProps in modo da ispezionare la richiesta e richiamare getProps solo per determinate richieste.

Per una migliore comprensione del routing, esaminare il codice sorgente. Ecco alcuni file fondamentali di Retail React App da analizzare:

app/routes.jsx: dimostra la sintassi di tipo Express per la corrispondenza dei percorsi, inclusi i parametri route denominati.
app/pages/product-detail/index.jsx: questo componente di esempio per la pagina di dettagli prodotto (PDP) include funzioni personalizzate per getProps e shouldGetProps.
app/components/_app_config/index.jsx: include codice di configurazione esteso e una funzione getProps a livello di app.

Per un approccio di routing alternativo, consultare Risoluzione degli URL.

Consultare la documentazione su PWA Kit senza dimenticare la guida sull'architettura di Retail React App.