Upgrade a v3

A partire dalla v3 è possibile ottenere gli aggiornamenti di @salesforce/retail-react-app aggiungendo il modello come dipendenza in in package.json e abilitando l'estensibilità del modello nel proprio progetto.

Questa guida illustra come aggiornare un progetto PWA Kit da v2.7.x a v3.0.0.

Sono state aggiunte a PWA Kit v3 numerose funzionalità, tra cui:

🔨 Estensibilità del modello: è possibile diminuire ampiamente l'impatto del codice sui progetti e ridurre le difficoltà di sviluppo, il costo totale di proprietà e la necessità di aggiornamenti futuri. Per maggiori dettagli, vedere la guida Estensibilità del modello.

🪝 Integrazione "hook" @salesforce/commerce-sdk-react integration: consente di disaccoppiare le chiamate API dall'implementazione di un progetto, permette l'upgrade delle chiamate API come dipendenza di libreria npm e include diverse grandi funzionalità (tra le altre, la gestione degli stati) tramite TanStack Query. Vedere la documentazione di Commerce SDK React per iniziare.

⚛️ Importanti aggiornamenti alle librerie di fornitori, incluso il supporto di React 18, Node 16 / 18, Chakra 2 e tanto altro.

Una delle prime decisioni da prendere durante la migrazione da v2.7.x a v3.x è se sfruttare l'estensibilità del modello. Per poterne usufruire è necessario importare almeno un file da @salesforcef/retail-react-app (o un'altra app estendibile). È possibile scegliere il numero di file che si desidera ereditare dal modello di base, ma è necessario confermare di importarne almeno uno.

A questo punto valutare il numero di file che sono stati modificati rispetto al progetto originale generato tramite npx pwa-kit-create-app@2.x. Alcuni clienti hanno un numero di file elevato (forse centinaia), ma anche in questo caso è possibile che molti di essi non siano stati modificati. Questi file non modificati sono buoni candidati per l'importazione da @salesforce/retail-react-app, ma si consiglia di eseguire questa operazione gradualmente e prestando attenzione. Molti file in @salesforce/retail-react-app sono simili, ma sono stati modificati rispetto al loro stato precedente nella v2.x di Retail React App PWA Kit. In particolare, l'integrazione @salesforce/commerce-sdk-react (i dettagli della migrazione verranno trattati più approfonditamente in seguito) ha causato la modifica di un elevato numero di file in termini di importazioni e struttura dei file. L'intera directory commerce-api è stata rimossa da Retail React App.

A partire dalla versione 3.0.0, PWA Kit utilizza una strategia di recupero (fetch) withReactQuery diversa. Questa strategia sfrutta la libreria react-query e abilita le query nel passaggio di rendering SSR. @salesforce/retail-react-app utilizza @salesforce/commerce-sdk-react con tecnologia react-query.

Affinché gli hook funzionino sul lato server, è necessario inserire il componente AppConfig all'interno del nuovo componente di ordine superiore withReactQuery.

Per i progetti che cercano di eseguire l'upgrade a v3 e continuano a utilizzare getProps, inserire il componente AppConfig all'interno del componente withLegacyGetProps.

Modificare le dipendenze in package.json come segue:

Aggiornare i motori in package.json per supportare Node 18 e npm 9. Rimuovere @chakra-ui/system da peerDependencies in package.json poiché la versione 2 è l'ultima versione principale di Chakra.

È presente un bug in nswapi, che è una dipendenza di jest-environment-jsdom non compatibile con Chakra 2. Restituisce l'errore ':disabled):not([disabled]' is not a valid selector per alcuni dei test che utilizzano il componente Modal. Questo bug riguarda solo gli unit test, non l'esecuzione del browser. Viene utilizzato npm 8 e vengono aggiunti override per applicare la versione 2.2.2 del pacchetto nwsapi, mentre il supporto di npm 7 viene eliminato.

Aggiungere una proprietà overrides in package.json per applicare la versione del pacchetto:

Reinstallare le dipendenze per il progetto con npm i.

Per la migrazione di react-hook-form, consultare la documentazione ufficiale di react-hook-form disponibile qui. Nel progetto PWA devono essere apportate modifiche in due punti:

1. Spostare l'oggetto errors di form in un ulteriore livello di eliminazione per gli hook in app/components/forms/* poiché l'oggetto errors è stato spostato nell'oggetto formState.

2. Spostare le prop di rendering in Controller nella prop field. La firma di callback di Render restituisce un oggetto che contiene field e fieldState.

A differenza di quanto avveniva in React 17, a partire da React 18 gli avvisi di hydration vengono visualizzati come errori anziché come avvisi. Sono stati necessari alcuni aggiornamenti di codice per eliminare questi potenziali errori di hydration che impediscono la creazione dell'applicazione. È essenziale correggere questi errori per consentire all'app di eseguire il rendering isomorfico. Gli errori di questo tipo si verificano a causa di una mancata corrispondenza tra server e client. Se un componente o una pagina vengono renderizzati in modo condizionale, è necessario verificare che la procedura di hydration sia terminata prima di eseguire il rendering di qualsiasi codice specifico per client.

Nel progetto, creare una funzione di utilità per determinare se l'hydration è terminata. È possibile utilizzare una variabile integrata fornita da window.__HYDRATING__ in pwa-kit-react-sdk.

Aggiungere questa funzione ovunque si utilizzi il rendering condizionale. La funzione può essere aggiunta in vari punti di un progetto PWA Kit:

Fare clic qui per informazioni.

Se è installato un plug-in del browser che interferisce con il rendering del DOM, è possibile che venga restituito un errore di hydration nel piè di pagina. Ad esempio, se si utilizza l'estensione LastPass, è possibile visualizzare l'errore nel componente Subscribe nel piè di pagina, perché LastPass subentra nel rendering del browser per inserire un'icona che abilita il popup nel campo. Se questa situazione si verifica durante la procedura di hydration, viene visualizzato l'errore. Un semplice espediente che può essere adottato senza dover usare isHydrated() consiste nel cambiare l'ordine dei componenti di input nel modo seguente:

Per supportare Chakra 2 è necessario aggiornare alcuni file per i progetti basati sul modello Retail React App:

Rimuovere allowToggle nel componente Accordion perché allowMultiple e allowToggle non possono essere utilizzati contemporaneamente in Chakra 2.

Nel componente Footer l'importazione diretta di StylesProvider da @chakra-ui/react è deprecata. È necessario crearla tramite createStylesContext('Footer').

Impostare userEvent prima di richiamare qualsiasi azione e attendere negli unit test l'azione che utilizza userEvent, perché nella libreria di test di React v14.0.0 tutte le azioni utente sono asincrone ed è necessario richiamare setup prima di eseguirle.

Ad esempio:

Per ulteriori dettagli, consultare la documentazione ufficiale su userEvent della libreria di test.

In alternativa, per evitare di richiamare ripetutamente setup() in molti unit test, è possibile impostare userEvent in app/utils/test-util.js subito prima di eseguire il rendering del componente di test e restituirlo insieme ai risultati del rendering, in modo che il test possa eseguire le azioni utente senza dover richiamare setup().

In jest-setup esiste una dipendenza fittizia che può generare un errore di TextDecoder non definito in jest-setup.js. Aggiungere quanto segue a jest-setup.js:

Quando si effettua la migrazione dalla versione 2.x degli SDK PWA Kit o dai progetti generati tramite npx pwa-kit-create-app@2.x, il codice @salesforce/commerce-sdk-react viene notevolmente rifattorizzato per rimuovere la directory app/commerce-api/*. Non saranno più tali file a gestire la richiesta API e ad agire come SDK, ma saranno sostituiti da @salesforce/commerce-sdk-react per tali funzionalità. La release v3 degli SDK è correlata alla prima release di @salesforce/retail-react-app@^1.x perché gli SDK utilizzano molto questa libreria.

L'implementazione di @salesforce/commerce-sdk-react altera numerosi file in Retail React App. Per rendersi conto dell'entità delle modifiche, è possibile effettuare il confronto release-2.7.x → release-3.0.x in questo diff di Github e cercare @salesforce/commerce-sdk-react. Nel diff, prendere nota di tutti i casi di aggiunta di questa importazione.