升級至 v3

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

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

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

🔨 範本擴充性：大幅減少您專案的程式碼足跡，並降低開發辛勞、擁有成本和未來升級煩惱。如需更多詳細資料，請參閱範本擴充性指南。

🪝 @salesforce/commerce-sdk-react「Hook」整合：讓 API 呼叫與專案實作脫鉤，允許 API 呼叫升級為 npm 資產庫相依項目，並可經由 TanStack Query 引進許多優秀功能 (包括狀態管理和其他功能)。請參閱 Commerce SDK React 文件，立即開始使用！

⚛️ 主要供應商資產庫更新，包括 React 18、Node 16 / 18、Chakra 2 等的支援。

從 v2.7.x 遷移至 v3.x 時要做的第一個決定是，您是否想要使用範本擴充性。若要從中獲益，您必須從 @salesforcef/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 目錄。

從 v3.0.0 開始，PWA Kit 使用不同的擷取策略 withReactQuery。此策略使用 react-query 資產庫，並在 SSR 轉譯通道中啟用查詢。@salesforce/retail-react-app 使用 @salesforce/commerce-sdk-react，由 react-query 支援。

為了讓 Hook 在伺服器端運作，您需要使用新的高階元件 withReactQuery 包住您的 AppConfig 元件。

對於嘗試升級至 v3 並繼續使用 getProps 的專案，請使用 withLegacyGetProps 元件來包住您的 AppConfig 元件。

請變更 package.json 中的相依項目，如下所示：

更新 package.json 中的引擎，以支援 Node 18 和 npm 9。從 package.json 的 peerDependencies 中移除 @chakra-ui/system，因為版本 2 是最新的 Chakra 主要版本。

有一個 bug nswapi，它是 jest-environment-jsdom 的相依項目，但不相容於 Chakra 2。在使用 Modal 元件的某些測試中，它會擲出錯誤 ':disabled):not([disabled]' is not a valid selector。此 bug 只會影響單元測試，不會影響瀏覽器執行。我們使用 npm 8，且新增覆寫項目來強制執行 2.2.2 版本的 nwsapi 套件，並已停止支援 npm 7。

請將 overrides 屬性新增至 package.json，以強制執行套件版本：

使用 npm i 重新安裝專案的相依項目。

針對 react-hook-form 遷移，請閱讀此處的 react-hook-form 官方文件。在 PWA 專案中，有兩個地方需要變更：

1. 由於 errors 物件已移至 formState 物件，因此請將表單 errors 物件移至 app/components/forms/* 中 Hook 的另一層解構層。

2. 將 Controller 中的轉譯 Prop 移入 field Prop 中。Render 的回呼簽章會傳回一個包含 field 和 fieldState 的物件。

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

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

請在您使用條件式轉譯的任何地方新增此函式。PWA Kit 專案中有幾個地方可以新增此函式：

請參閱此處。

如果您已安裝某個瀏覽器外掛程式，而它干擾了 DOM 轉譯，則您會在頁尾收到 Hydration 錯誤。例如，如果您正在使用 LastPass 擴充元件，您會在頁尾看到有關 Subscribe 元件的錯誤，因為 LastPass 接管了瀏覽器的轉譯，以注入圖示來啟用欄位內快顯。如果這種接管發生在 Hydration 流程期間，將會顯示錯誤。在不使用 isHydrated() 的情況下，您可以使用一個簡單解法，是像這樣交換輸入元件的順序：

為了支援 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 中，請記下所有加入此匯入的新增項目。