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 all’architettura di Retail React App in PWA (Progressive Web App) Kit versione 2.x:
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.)
1.eslintignore Exclusion rules for ESLint
2.eslintrc.js Code style rules for ESLint
3.gitignore Exclusion rules for git
4.prettierignore Exclusion rules for Prettier code formatting
5.prettierrc.yaml Code formatting rules for Prettier
6├── app/ Application code lives here
7 ├── assets/svg/ SVG icon assets
8 ├── commerce-api/ Commerce API client and hooks
9 ├── components/ React components
10 │ ├── _app Root component
11 │ ├── _app-config Wrapper component for injecting custom code
12 │ └── _error Generic error component
13 │ └── ...
14 ├── constants.js Constants imported throughout the app
15 ├── contexts/ React contexts
16 ├── hoc Contains higher-order components
17 ├── hooks/ React hooks
18 ├── main.jsx Client-side rendering entry point
19 ├── pages/ Retail-oriented pages like home, PLP, and PDP
20 ├── partials/ Partials imported throughout the app
21 ├── request-processor.js Request processing functions (run at CDN edge)
22 ├── request-processor.test.js Tests for request processing functions
23 ├── routes.jsx Maps request paths to route components
24 ├── routes.test.js Tests for mapping request paths to route components
25 └── ssr.js Server-side rendering entry point
26 ├── static/ Static assets
27 │ └── manifest.json Manifest for PWA features like add to home screen
28 │ └── ...
29 ├── theme/ Theme files for components
30 │ ├── components/
31 │ │ ├── base/ Theme files for Chakra UI components
32 │ │ └── project/ Theme files for custom components
33 │ ├── foundations/ Frequently used theme values like colors and spacing
34 │ └── index.js
35 ├── translations/ Translations for react-intl
36 ├── utils/ Utilities imported throughout the app
37babel.config.js Transpilation rules for Babel
38cache-hash-config.json Cache breaking hash used by the CDN
39CHANGELOG.md Chronological list of changes to the template
40├── config/ Configuration files
41 ├── default.js Default configuration file
42 ├── mocks/ Default configuration file with mock values for unit testing
43 └── sites.js Identifies sites configured in Business Manager. Includes localization details.
44jest-setup.js Unit testing setup for Jest
45jest.config.js Unit testing configuration for Jest
46LICENSE Software licensing agreement
47node_modules/ Package dependencies
48package-lock.json Package configuration lock file
49package.json Package configuration
50README.md Basic documentation
51tests/ Unit tests
52worker/ Service workerRetail 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:
| Nome | Descrizione |
|---|---|
analyze-build | Crea il progetto in modalità Production e genera due report webpack-bundle-analyzer. Utilizzare i report per monitorare le dimensioni del bundle di codice. |
compile-messages | Compila tutti i messaggi localizzati in formato AST. |
extract-messages | Estrae automaticamente i messaggi dell’impostazione locale predefinita dai componenti React. |
format | Formatta il codice con Prettier. |
lint | Individua stili di codice incoerenti con ESlint. |
lint:fix | Corregge automaticamente gli errori ESlint. |
prod:build | Crea il progetto in modalità Production. |
push | Esegue il push del bundle di codice (artefatti di compilazione Production) in Managed Runtime. |
save-credentials | Salva le credenziali di Runtime Admin in locale (per il comando di push). |
start | Avvia il server SSR. |
start:inspect | Avvia il server SSR utilizzando il controllo Node.js. |
start:pseudolocale | Avvia il server SSR con una pseudo-impostazione locale. |
test | Esegue unit test con Jest. |
test:lighthouse | Esegue test Lighthouse. |
test:max-file-size | Esegue 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:
1npm run testPer 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:
1npm run test:lighthouseLo 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.
Note
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 config/default.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:
1const MyPage = (props) => {
2 const {categories} = props
3 return <div>There are {categories.length} categories.</div>
4}
5
6MyPage.getProps = async ({api}) => {
7 categories = await api.shopperProducts.getCategory({
8 parameters: {id: categoryId, levels: 0}
9 })
10
11 return {categories}
12}Il wrapper CommerceAPI al momento utilizza Commerce API per prodotti, promozioni, certificati regalo e ricerca. Ogni funzionalità viene fornita con il proprio set di endpoint, documentati separatamente nella Guida di riferimento alle API di B2C Commerce.
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.
Note
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:
| Nome | Descrizione |
|---|---|
| Loadable Components | Accelera le prestazioni mediante la suddivisione del codice dei bundle di grandi dimensioni. |
| ReactDOM | Fornisce metodi specifici per DOM utilizzabili al livello superiore dell’applicazione. |
| ReactDOMServer | Fornisce il metodo renderToString() che prerenderizza l’HTML sul lato server. |
| React Helmet | Consente di gestire le modifiche del tag head del documento. |
| React Router | Associa 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.
La Retail React App importa configurazioni Webpack già pronte per il lato client e lato server dal 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.
app/pages.
j