升級至 v3
從 v3 開始,現在可以將 @salesforce/retail-react-app
新增為 npm 相依項目,並在專案中啟用範本擴充性,來使用 @salesforce/retail-react-app
更新。
這份指南說明如何將 PWA Kit 專案從 v2.7.x 更新至 v3.0.0。
我們為 PWA Kit v3 增加了許多新功能,包括:
⚛️ 必要:
getProps
重大改變- 主要資產庫更新,包括 React 18、Node 18、Chakra 2 等的支援
🔨 選擇性:範本擴充性 — 大幅減少您專案的程式碼足跡,並降低開發辛勞、擁有成本和未來升級煩惱。如需更多詳細資料,請參閱 Template Extensibility (範本擴充性) 指南!
🪝 選擇性: @salesforce/commerce-sdk-react「Hook」整合 — 讓 API 呼叫與專案實作脫鉤,允許 API 呼叫升級為 npm 資產庫相依項目,並可經由 TanStack Query 引進許多優秀功能 (包括狀態管理和其他功能)。請參閱 Commerce SDK React 文件,立即開始使用!
PWA Kit SDK 已移至 @salesforce
NPM 組織。若要升級至 v3,請安裝新的套件,並替換以下套件的所有匯入陳述式:
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
從 v3.0.0 開始,PWA Kit 引進了新的資料擷取策略 withReactQuery
。此策略使用 react-query 庫,可讓您編寫 React Hook,以同構方式擷取資料。與 getProps
不同,您不再需要為用戶端和伺服器端重複資料擷取邏輯。在此版本中,@salesforce/retail-react-app
預設使用由 react-query
支援的 @salesforce/commerce-sdk-react
。
- 您可以同時使用
withReactQuery
和withLegacyGetProps
。 getProps
和shouldGetProps
已從 Retail React App 頁面的預設範本中移除,但未棄用。對這些方法的長期支援仍然存在。
請變更 package.json 中的相依項目,如下所示。從 peerDependencies
中刪除 @chakra-ui/system
,並將其包含在 dependencies
或 devDependencies
下。
更新 package.json 中的引擎,以支援 Node 18 和 npm 9。
使用 npm i
重新安裝專案的相依項目。
從 v2.7.x 遷移到 v3.x 時,可以選擇是否使用範本擴充性。要從中受益,您必須從 @salesforce/retail-react-app
(或將來的其他可擴充範本) 匯入至少一個檔案。
之後,請考量您從透過 npx pwa-kit-create-app@2.x
產生的原始專案中,已經修改了多少檔案。有些客戶擁有大量 (可能數百個) 檔案,但即便如此,其中大部分都是未經修改的。這些未修改過的檔案是從 @salesforce/retail-react-app
匯入的良好候選項目,但我們建議您小心地逐步執行這個程序。@salesforce/retail-react-app
中的許多檔案都很相似,但自 PWA Kit Retail React App v2.x
以來,其原先狀態已經發生改變。特別是,@salesforce/commerce-sdk-react
整合 (稍後將詳細介紹遷移細節) 導致大量檔案在匯入和檔案結構方面發生了變化,應用程式中移除了整個 commerce-api
目錄。
當您遷移專案以使用範本擴充性時,請注意,PWA Kit SDK 2.x 版本和透過 npx pwa-kit-create-app@2.x
產生的專案不依賴 @salesforce/commerce-sdk-react
,但較新的程式碼 @salesforce/retail-react-app@^1.x
則大量使用此資產庫,會觸及並變更許多檔案。若要感受一下改變的幅度,您可以到此 Github diff https://github.com/SalesforceCommerceCloud/pwa-kit/compare/release-2.7.x...release-3.0.x?diff=unified#files_bucket 比較 release-2.7.x
→ release-3.0.x
,搜尋 @salesforce/commerce-sdk-react
,並記下所有加入此匯入的新增項目。
如果您的應用程式嘗試與 2.x
版本 (包含 app/commerce-api
目錄) 共用程式碼,則可能會在套件中新增不必要的程式碼,因為該程式碼 (以兩種截然不同的形式) 同時存在於 commerce-api
資料夾和 @salesforce/commerce-sdk-react
npm 模組中。
從 v3.0.0 開始,PWA Kit 使用不同的擷取策略 withReactQuery
。此策略使用 react-query 資產庫,並在 SSR 轉譯通道中啟用查詢。@salesforce/retail-react-app
使用 @salesforce/commerce-sdk-react
,由 react-query
支援。
為了讓 Hook 在伺服器端運作,您需要使用新的高階元件 withReactQuery
包住您的 AppConfig
元件。
作為遷移到 ReactQuery 當作預設擷取策略的一部分,@salesforce/retail-react-app@^1
需要進行變更,以確保舊版 getProps()
呼叫可以繼續運作。
完成上述相依性升級後,您可能會在專案中遇到與下列程式庫相關的問題。在以下各節中,我們提出了化解這些問題的解決方案。您的專案細節會有所不同,建議的解決方案應被視為指導方針,而不是絕對的規則。
針對 react-hook-form
遷移,請閱讀此處的 react-hook-form 官方文件。在 PWA 專案中,有兩個地方需要變更:
- 由於
errors
物件已移至formState
物件,因此請將表單errors
物件移至app/components/forms/
中 Hook 的另一層解構層。
- 將
Controller
中的轉譯 Prop 移入field
Prop 中。Render
的回呼簽章會傳回一個包含field
和fieldState
的物件。
從 React 18 開始,Hydration 警告會顯示為錯誤,而不是像 React 17 那樣顯示為警告。您需要更新一些程式碼來抑制這些潛在錯誤,防止應用程式因為 Hydration 錯誤而無法建置。修正這些錯誤非常重要,可確保應用程式能夠同構轉譯。發生此錯誤的原因是,伺服器或用戶端之間出現不相符。如果某個元件或頁面是在符合條件時才進行轉譯,則您必須確保在轉譯任何用戶端專屬程式碼之前,已先完成 Hydration。
在您的專案中,建立一個公用程式函式來判斷是否已完成 Hydration。您可以使用 pwa-kit-react-sdk
中 window.__HYDRATING__
提供的內建變數。
如果您的專案使用與 Retail React App 範本不同的 @chakra-ui/react
資產庫元件和 API,請參閱官方的 Chakra 2 遷移文件。
為了支援 Chakra 2,針對根據 Retail React App 範本的專案,有一些檔案需要更新:
移除 Accordion
元件中的 allowToggle
,因為在 Chakra 2 中不能同時使用 allowMultiple
和 allowToggle
。
在 Footer
元件中,已棄用直接從 @chakra-ui/react
匯入 StylesProvider
。您必須改由 createStylesContext('Footer')
建立之。
在呼叫任何動作之前先設定 userEvent
,然後等待使用 userEvent
的單元測試中的動作,因為在 React 測試庫 v14.0.0 中,所有使用者動作都是非同步的,需要在執行使用者動作之前呼叫 setup
。
舉例來說:
如需更多詳細資料,請參閱 testing-library 的 userEvent 官方文件。
或者,為了避免在許多單元測試中重複呼叫 setup()
,您可以在轉譯測試元件之前,在 app/utils/test-util.js
中設定 userEvent
,使它隨轉譯結果一起傳回,如此可讓測試執行使用者動作,而無需呼叫 setup()
。
在 jest-setup 中,有一個模擬相依項目可能會擲出關於 TextDecoder
未在 jest-setup.js.
中定義的錯誤。將以下內容加入 jest-setup.js
:
從 PWA Kit SDK 2.x 版或透過 npx pwa-kit-create-app@2.x
產生的專案遷移時,@salesforce/commerce-sdk-react
程式碼已大幅重構,移除了 app/commerce-api/
目錄。以往處理 API 要求並充當 SDK 的檔案已不再使用,現在改以 @salesforce/commerce-sdk-react
取代該功能。SDK 的 v3 版本與 @salesforce/retail-react-app@^1.x
的第一個版本息息相關,因為 SDK 大量使用此資產庫。
@salesforce/commerce-sdk-react
的實作改變了 Retail React App 中的許多檔案。若要感受一下改變的大小,您可以到此 GitHub diff 比較 release-2.7.x
和 release-3.0.x
,並搜尋 @salesforce/commerce-sdk-react
。在 diff 中,請記下所有包含此匯入的新增項目。