升级到 v3

自 v3 开始，现在可以通过将 @salesforce/retail-react-app 更新添加为 npm 依赖项并在项目中启用模板可扩展性来使用更新。

本指南介绍如何将 PWA Kit 项目从 v2.7.x 更新到 v3.0.0。

我们为 PWA Kit v3 添加了许多新功能，包括：

⚛️ 需要：

  • getProps 突破性更改
  • 主要库更新，包括对 React 18、Node 18、Chakra 2 等的支持

🔨 自选：模板可扩展性 — 显著减少项目的代码占用量，并减少开发工作、拥有成本和未来升级的麻烦。有关更多详细信息，请参阅模板可扩展性指南！

🪝 可选： @salesforce/commerce-sdk-react "hooks" 集成 — 将 API 调用与项目实施解耦，允许 API 调用作为 npm 库依赖项进行升级，并通过 TanStack 查询带来许多出色功能（包括状态管理等）。请参阅 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 中的很多文件都相似，但已较 v2.x 版 PWA Kit Retail React App 之前的状态发生了变化。特别是，@salesforce/commerce-sdk-react 集成（稍后将更详细地介绍迁移细节）导致大量文件在导入和文件结构方面发生变化。整个 commerce-api 目录已从 Retail React App 中删除。

当迁移项目以使用模板可扩展性时，请注意，2.x 版本的 PWA Kit SDK 和通过 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 使用由 react-query 支持的 @salesforce/commerce-sdk-react。

为了使 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 中的渲染道具移入 field 道具中。Render 的回调签名返回包含 field 和 fieldState 的对象。

自 React 18 开始，水合警告显示为错误，而不是像 React 17 中那样显示为警告。需要更新一些代码来抑制这些潜在错误，这些错误会在出现水合错误时阻止应用程序构建。修复这些错误以确保应用程序能够同构渲染至关重要。发生此错误的原因是服务器或客户端之间不匹配。如果组件或页面碰巧有条件渲染，则必须确保在渲染任何特定于客户端的代码之前完成水合作用。

在您的项目中，创建一个实用函数来确定水合是否已完成。您可以使用 window.__HYDRATING__ 在 pwa-kit-react-sdk 中提供的内置变量。

如果您的项目使用 @chakra-ui/react 库中与 Retail React App 模板不同的组件和 API，请查看官方 Chakra 2 迁移文件。

为了支持 Chakra 2，有一些文件需要为基于 Retail React App 模板的项目进行更新：

删除 Accordion 组件中的 allowToggle，因为 allowMultiple 和 allowToggle 不能在 Chakra 2 中同时使用。

在 Footer 组件中，已废弃从 @chakra-ui/react 直接导入 StylesProvider。您必须通过 createStylesContext('Footer') 创建它。

在调用任何操作之前设置 userEvent，并在使用 userEvent 的单元测试中等待该操作，因为在 React 测试库 v14.0.0 中，所有用户操作都是异步的，并且需要在执行用户操作之前调用 setup 。

例如：

有关更多详细信息，请参阅测试库的 userEvent 的官方文档。

或者，为了避免在许多单元测试中重复调用 setup()，您可以在渲染测试组件之前通过 app/utils/test-util.js 设置您的 userEvent，并将其与渲染结果一起返回，以便测试可以执行用户操作，而无需调用 setup()。

在 jest-setup 中，有一个模拟依赖项可能会引发关于 TextDecoder 在 jest-setup.js. 中未定义的错误。将以下内容添加到 jest-setup.js：

从 2.x 版 PWA Kit SDK 或通过 npx pwa-kit-create-app@2.x 生成的项目进行迁移时，@salesforce/commerce-sdk-react 代码已经过重大重构，以删除 app/commerce-api/ 目录。而不是那些处理 API 请求并充当 SDK 的文件 @salesforce/commerce-sdk-react 取代了该功能。v3 版 SDK 与第一版 @salesforce/retail-react-app@^1.x 相关，因为 SDK 大量使用此库。

@salesforce/commerce-sdk-react 的实现更改了 Retail React App 中的许多文件。要了解更改的大小，请将 release-2.7.x 与此 GitHub 差异中的 release-3.0.x 进行比较并搜索 @salesforce/commerce-sdk-react。在差异中，记下包含此导入的所有添加内容。