Upgrade a v3
A partire dalla v3 è possibile utilizzare gli aggiornamenti @salesforce/retail-react-app
aggiungendo il modello come dipendenza npm 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:
⚛️ Obbligatorio:
- Modifica fondamentale a
getProps
- Sostanziali aggiornamenti della libreria, incluso il supporto per React 18, Node 18, Chakra 2 e altro ancora
🔨 Facoltativo: Estensibilità del modello — Consente di 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!
🪝 Facoltativo: 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!
Gli SDK PWA Kit sono stati spostati nell'organizzazione NPM @salesforce
. Per eseguire l'aggiornamento alla versione 3, installare i nuovi pacchetti e sostituire tutte le istruzioni di importazione per i pacchetti seguenti:
pwa-kit-react-sdk
>@salesforce/pwa-kit-react-sdk@^3
pwa-kit-runtime
>@salesforce/pwa-kit-runtime@^3
pwa-kit-dev
>@salesforce/pwa-kit-dev@^3
pwa-kit-create-app
>@salesforce/pwa-kit-create-app@^3
retail-react-app
>@salesforce/retail-react-app@^3
A partire dalla versione 3.0.0, PWA Kit introduce una nuova strategia di recupero dati withReactQuery
. Questa strategia utilizza la libreria react-query e consente di scrivere hook React per recuperare i dati in maniera isomorfa. A differenza di getProps
, non è più necessario duplicare la logica di recupero dati per il lato client e il lato server. Per impostazione predefinita, in questa versione @salesforce/retail-react-app
utilizza @salesforce/commerce-sdk-react
che è supportato da react-query
.
- È possibile utilizzare contemporaneamente sia
withReactQuery
siawithLegacyGetProps
. getProps
eshouldGetProps
sono state rimosse dal modello predefinito delle pagine della Retail React App, ma non sono deprecate. Il supporto a lungo termine per questi metodi rimane.
Modificare le dipendenze in package.json come illustrato di seguito. Rimuovere @chakra-ui/system
da peerDependencies
e includerlo sotto dependencies
o devDependencies
.
Aggiornare i motori in package.json per supportare il nodo 18 e npm 9.
Reinstallare le dipendenze per il progetto con npm i
.
Quando si esegue la migrazione dalla versione 2.7.x alla versione 3.x è possibile scegliere se utilizzare l'estensibilità del modello. Per usufruirne, è necessario importare almeno un file da @salesforce/retail-react-app
(o un altro modello estensibile in futuro).
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.
Quando si esegue la migrazione di un progetto per utilizzare l'estensibilità del modello, tenere presente che la versione 2.x degli SDK PWA Kit e i progetti generati tramite npx pwa-kit-create-app@2.x
non hanno una dipendenza da @salesforce/commerce-sdk-react
, mentre il codice più recente di @salesforce/retail-react-app@^1.x
fa un uso intensivo di questa libreria, che interessa e modifica molti file. Per rendersi conto dell'entità delle modifiche, è possibile effettuare il confronto release-2.7.x
→ release-3.0.x
in questo diff di Github https://github.com/SalesforceCommerceCloud/pwa-kit/compare/release-2.7.x...release-3.0.x?diff=unified#files_bucket, cercare @salesforce/commerce-sdk-react
e prendere nota di tutti i casi di aggiunta di questa importazione.
Se l'app tenta di condividere del codice con la versione 2.x
(che include la directory app/commerce-api
), si rischia di aggiungere codice non necessario al bundle dove tale codice esiste già (in due forme molto diverse) sia nella cartella commerce-api
sia nel modulo npm @salesforce/commerce-sdk-react
.
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
supportato da react-query
.
Affinché gli hook funzionino sul lato server è necessario inserire il componente AppConfig
all'interno del nuovo componente di ordine superiore withReactQuery
.
Nell'ambito della migrazione a ReactQuery come strategia di recupero predefinita, è necessaria una modifica a @salesforce/retail-react-app@^1
per garantire che le chiamate getProps()
legacy continuino a funzionare.
Quando si completano gli aggiornamenti delle dipendenze descritti in precedenza, è possibile che si verifichino problemi nel progetto relativi alle librerie seguenti. Nelle sezioni che seguono proponiamo soluzioni per risolvere tali problemi. Le caratteristiche specifiche del proprio progetto varieranno e le soluzioni proposte dovrebbero essere trattate come linee guida e non come regole assolute.
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:
- Spostare l'oggetto
errors
di form in un ulteriore livello di eliminazione per gli hook inapp/components/forms/
poiché l'oggettoerrors
è stato spostato nell'oggettoformState
.
- Spostare le prop di rendering in
Controller
nella propfield
. La firma di callback diRender
restituisce un oggetto che contienefield
efieldState
.
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
.
Se il progetto utilizza componenti e API della libreria @chakra-ui/react
diversi dal modello Retail React App, consultare la documentazione ufficiale sulla migrazione di Chakra 2.
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
modifica molti file di Retail React App. Per avere un'idea delle dimensioni delle modifiche, confrontare release-2.7.x
con release-3.0.x
in questo diff di GitHub e cercare @salesforce/commerce-sdk-react
. Nel diff, prendere nota di tutte le aggiunte che includono questa importazione.