升級至 v3

從 v3 開始,現在可以將 @salesforce/retail-react-app 新增為 npm 相依項目,並在專案中啟用範本擴充性,來使用 @salesforce/retail-react-app 更新。

這份指南說明如何將 PWA Kit 專案從 v2.7.x 更新至 v3.0.0。

我們為 PWA Kit v3 增加了許多新功能,包括:

⚛️ 必要

  • getProps 重大改變
  • 主要資產庫更新,包括 React 18Node 18Chakra 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

  • 您可以同時使用 withReactQuerywithLegacyGetProps
  • getPropsshouldGetProps 已從 Retail React App 頁面的預設範本中移除,但未棄用。對這些方法的長期支援仍然存在。

請變更 package.json 中的相依項目,如下所示。從 peerDependencies 中刪除 @chakra-ui/system,並將其包含在 dependenciesdevDependencies 下。

更新 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.xrelease-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 專案中,有兩個地方需要變更:

  1. 由於 errors 物件已移至 formState 物件,因此請將表單 errors 物件移至 app/components/forms/ 中 Hook 的另一層解構層。
  1. Controller 中的轉譯 Prop 移入 field Prop 中。Render 的回呼簽章會傳回一個包含 field fieldState 的物件。

從 React 18 開始,Hydration 警告會顯示為錯誤,而不是像 React 17 那樣顯示為警告。您需要更新一些程式碼來抑制這些潛在錯誤,防止應用程式因為 Hydration 錯誤而無法建置。修正這些錯誤非常重要,可確保應用程式能夠同構轉譯。發生此錯誤的原因是,伺服器或用戶端之間出現不相符。如果某個元件或頁面是在符合條件時才進行轉譯,則您必須確保在轉譯任何用戶端專屬程式碼之前,已先完成 Hydration。

在您的專案中,建立一個公用程式函式來判斷是否已完成 Hydration。您可以使用 pwa-kit-react-sdkwindow.__HYDRATING__ 提供的內建變數。

如果您的專案使用與 Retail React App 範本不同的 @chakra-ui/react 資產庫元件和 API,請參閱官方的 Chakra 2 遷移文件

為了支援 Chakra 2,針對根據 Retail React App 範本的專案,有一些檔案需要更新:

移除 Accordion 元件中的 allowToggle,因為在 Chakra 2 中不能同時使用 allowMultipleallowToggle

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.xrelease-3.0.x,並搜尋 @salesforce/commerce-sdk-react。在 diff 中,請記下所有包含此匯入的新增項目。