Retail React App

Retail React App è un set di codici di esempio e di strumenti progettati per avviare la creazione di uno storefront basato su API che viene ospitato in Managed Runtime. Questa guida sull'architettura descrive la struttura e i contenuti di Retail React App, mettendone in evidenza la natura flessibile e open-source.

Tutti i progetti PWA Kit iniziano con lo stesso set di file. All'inizio di un progetto tali file vengono generati mediante esecuzione di uno script. (Questa procedura è descritta dettagliatamente nella guida della sezione Inizia.)

Per una panoramica del funzionamento di Retail React App, esaminare in primo luogo la struttura dei file. Ecco un elenco di tutti i file e tutte le directory di un progetto appena generato, accompagnati da una breve descrizione. (Le tecnologie citate nelle descrizioni vengono illustrate in maggior dettaglio più avanti in questa guida.)

Retail React App include numerosi script che consentono di automatizzare le attività di sviluppo di routine. Utilizzare il comando npm run <SCRIPT_NAME> per eseguirli dal terminale.

Ecco un elenco completo di tutti gli script inclusi, con una descrizione di ciascuno:

NomeDescrizione
analyze-buildCrea il progetto in modalità Production e genera due report webpack-bundle-analyzer. Utilizzare i report per monitorare le dimensioni del bundle di codice.
compile-messagesCompila tutti i messaggi localizzati in formato AST.
extract-messagesEstrae automaticamente i messaggi dell'impostazione locale predefinita dai componenti React.
formatFormatta il codice con Prettier.
lintIndividua stili di codice incoerenti con ESlint.
lint:fixCorregge automaticamente gli errori ESlint.
prod:buildCrea il progetto in modalità Production.
pushEsegue il push del bundle di codice (artefatti di compilazione Production) in Managed Runtime.
save-credentialsSalva le credenziali di Runtime Admin in locale (per il comando di push).
startAvvia il server SSR.
start:inspectAvvia il server SSR utilizzando il controllo Node.js.
start:pseudolocaleAvvia il server SSR con una pseudo-impostazione locale.
testEsegue unit test con Jest.
test:lighthouseEsegue test Lighthouse.
test:max-file-sizeEsegue un test delle dimensioni del bundle.

Il progetto è dotato di due gruppi di test di esempio per motivi di controllo qualità: unit test creati con Jest e React Testing Library.

Gli unit test sono inclusi nelle rispettive directory insieme a ciascun componente di pagina.

Per avviare gli unit test, eseguire il seguente comando nel terminale:

Per ulteriori informazioni sui test dello storefront, esaminare il codice sorgente dei gruppi di test di esempio e consultare la documentazione di Jest e React Testing Library.

Secondo le misurazioni effettuate dal gruppo di test Lighthouse di Google, Retail React App registra fin dall'inizio punteggi eccellenti in termini di prestazioni. Per monitorare più facilmente i punteggi Lighthouse per tutta la fase di sviluppo, utilizzare il seguente script:

Lo script esegue Lighthouse nello storefront per tre volte e carica su Google i punteggi mediani di ogni categoria. Google utilizza quindi tali punteggi per generare un report. Lo script genera un link al report prima del termine.

Per utilizzare le Salesforce API per accedere ai dati degli acquirenti, un amministratore deve completare le attività descritte in Impostazione dell'accesso API.

I dati degli acquirenti in Retail React App sono accessibili tramite una classe denominata CommerceAPI creata sul client commerce-sdk-isomorphic. La classe CommerceAPI può essere personalizzata in app/commerce-api/index.js e configurata in app/api.config.js.

La classe CommerceAPI viene automaticamente inserita nel metodo getProps di ogni pagina. Ad esempio, è possibile accedere al wrapper API da un componente di pagina come il seguente:

Il wrapper CommerceAPI al momento utilizza Commerce API per prodotti, promozioni, certificati regalo e ricerca. Ciascuna di queste funzionalità è dotata di un proprio set di endpoint, documentati separatamente nella sezione Riferimento di B2C Commerce API.

Per autorizzare le richieste API per conto di acquirenti registrati e utenti ospite, la classe CommerceAPI si basa su una Salesforce Commerce API denominata Shopper Login and API Access Service (SLAS).

Per carrelli e ordini, la classe CommerceAPI utilizza anche Open Commerce API (OCAPI).

Le istruzioni per l'impostazione di Salesforce Commerce API (inclusa SLAS) e OCAPI sono disponibili in Impostazione dell'accesso API.

La libreria di componenti di Chakra UI è una tecnologia nuova, ma compatibile con gli ambienti Production, utilizzata in Retail React App. Include oltre 50 componenti di interfaccia utente, tutti con eccellenti caratteristiche di accessibilità e usabilità. I componenti possono essere personalizzati con prop di stile o mediante oggetti JavaScript per stili più avanzati (CSS-in-JS). Tutti i componenti Chakra sono dotati di stili di base ben progettati, che possono essere sostituiti con un sistema di temi.

Il sistema di applicazione temi di Chakra è basato sulla specifica di temi Styled System. È possibile personalizzare l'aspetto dei componenti in base al proprio brand aggiornando i valori nella directory app/theme .

L'applicazione di temi è disponibile per la maggior parte dei componenti riutilizzabili in app/components, ma non per pagine quali la pagina dettagli prodotto o la pagina elenco prodotti. Per cambiare lo stile di queste pagine, modificare gli stili incorporati nel codice sorgente per i rispettivi componenti di pagina in app/pages.

Per includere icone SVG personalizzate nel progetto, aggiungerle alla directory app/assets/svg, importarle in app/components/icons/index.js ed esportare il componente icon React come segue: export const MyCustomIcon = icon('my-custom-icon').

Le icone SVG importate vengono pacchettizzate in uno sprite SVG al momento della compilazione e lo sprite viene incluso nell'HTML renderizzato sul lato server.

PWA Kit React SDK è una libreria che supporta la pipeline di rendering isomorfo per gli storefront PWA Kit. Contiene molti componenti, classi e funzioni chiave su cui si basa Retail React App. Ad esempio, la funzione render() in app/ssr.js che avvia l'intero processo di rendering e routing viene importata dall'SDK.

L'SDK estrae alcuni dei dettagli di implementazione per i processi di rendering, caching e invio al proxy di lato server, offrendo al tempo stesso molte opportunità per personalizzarne il funzionamento. Inoltre, fornisce utilità e strumenti generici per la gestione di un unico set di codice renderizzabile sia sul lato client sia sul lato server.

Salesforce gestisce l'SDK come pacchetto npm distinto da Retail React App per semplificare i miglioramenti.

PWA Kit React SDK e l'intera Retail React App sono progetti open-source e sono disponibili su GitHub. I contributi della community di Commerce Cloud sono molto apprezzati.

In questa sezione vengono illustrate le tecnologie open-source più comunemente utilizzate da Retail React App, ma anche più difficili da sostituire con tecnologie alternative. Sono state selezionate quindi non solo per le caratteristiche prestazionali, ma anche per la loro reputazione. Ciascuna di esse viene mantenuta attivamente ed è altamente personalizzabile, ben documentata e ampiamente utilizzata.

Ecco una breve panoramica di ciascuna di queste tecnologie, molte delle quali potrebbero essere già note:

Babel compila il codice JavaScript per renderlo compatibile con un'ampia gamma di browser e ambienti Node.js. Trasforma la sintassi di linguaggio avanzata e aggiunge polyfill a qualsiasi funzionalità mancante nell'ambiente.

Express è un noto framework open-source per server web in linguaggio JavaScript che viene eseguito nell'ambiente di runtime Node.js. Gestisce le richieste HTTP per le route definite come punti di ingresso per lo storefront.

Express consente di configurare le comuni impostazioni di server web, come la porta di connessione e l'ubicazione dei modelli per la restituzione della risposta. Consente inoltre di aggiungere middleware supplementare per l'elaborazione delle richieste in qualsiasi punto della pipeline di gestione richieste.

Tutto il codice di lato server per un'applicazione PWA Kit viene eseguito su Node.js, un ambiente di runtime open-source per JavaScript. L'ambiente di runtime omette le API JavaScript specifiche del browser e include le proprie API per accedere alle funzionalità del sistema operativo dell'host (ad esempio il file system) in modalità multipiattaforma.

Node.js utilizza un'architettura non bloccata o asincrona, che è ideale per la creazione di storefront altamente scalabili e con elevati volumi di dati.

React è un framework sviluppato da Facebook per creare app a pagina singola caratterizzate da interfacce utente veloci, fluide e immersive.

In un'app React l'interfaccia utente viene creata con componenti discreti solitamente disposti in gerarchie complesse. In un'app React ben progettata ogni componente è responsabile di un solo processo, che spesso ha l'unico scopo di contenere altri componenti.

La gerarchia dei componenti in Retail React App è progettata per essere ampliata o modificata. È possibile compilare la propria app sulla base dei componenti inclusi o sostituendo questi ultimi con componenti nuovi.

Pacchetti correlati a React:

NomeDescrizione
Loadable ComponentsAccelera le prestazioni mediante la suddivisione del codice dei bundle di grandi dimensioni.
ReactDOMFornisce metodi specifici per DOM utilizzabili al livello superiore dell'applicazione.
ReactDOMServerFornisce il metodo renderToString() che prerenderizza l'HTML sul lato server.
React HelmetConsente di gestire le modifiche del tag head del documento.
React RouterAssocia i percorsi URL ai componenti React. I percorsi possono essere espressi come schemi che vengono abbinati in ordine decrescente di specificità.

Webpack consolida il codice in uno o più bundle. Questi bundle vengono distribuiti in Managed Runtime, quindi caricati nel browser nell'ambito della procedura di hydration.

Retail React App importa configurazioni Webpack predefinite per il form di lato client e di lato server da PWA Kit React SDK. Nella maggior parte dei casi non è necessario modificare queste configurazioni; tuttavia, qualora vengano modificate, è possibile estendere la configurazione Webpack in webpack.config.js.

Ora che sono stati illustrati i contenuti e la struttura di Retail React App, è giunto il momento di approfondire! Iniziare esplorando il codice sorgente, in particolare i componenti di e-commerce in app/pages.