PWA Kit v2.x 中的 Retail React App

Retail React App 是一组示例代码和工具，旨在让您抢先构建基于 API 的网店，并将其在 Managed Runtime 上托管。Progressive Web App (PWA) Kit 版本 2.x 中的 Retail React App 的此体系结构指南：

描述其结构和内容
突出其灵活的开源基础

所有 PWA Kit 项目均以相同的文件集开始。在项目开始时，这些文件通过运行脚本生成。（此过程在入门指南中有完整介绍。）

要大致了解 Retail React App 的工作原理，应首先了解其文件结构。以下是新生成项目的所有文件和目录的列表，每个文件和目录都有简要说明。（描述中提到的技术将在本指南后面详细介绍。）

为了自动化日常开发任务，Retail React App 包含几个脚本。使用命令 npm run <SCRIPT_NAME> 从终端运行它们。

以下是所有包含脚本的完整列表以及每个脚本的说明：

名称	说明
`analyze-build`	在生产模式下构建项目并创建两个 webpack-bundle-analyzer 报告。使用报告监控代码捆绑包的大小。
`compile-messages`	将所有本地化消息编译为 AST 格式。
`extract-messages`	自动从 React 组件中提取默认区域设置的消息。
`format`	使用 Prettier 格式化代码。
`lint`	使用 ESlint 查找不一致的代码样式。
`lint:fix`	自动修复 ESlint 错误。
`prod:build`	在生产模式中构建项目。
`push`	将代码捆绑包（生产构建工件）推送到 Managed Runtime。
`save-credentials`	在本地保存 Runtime Admin（运行时管理员）登录信息（用于推送命令）。
`start`	启动 SSR 服务器。
`start:inspect`	使用 Node.js 检查器启动 SSR 服务器。
`start:pseudolocale`	使用伪区域设置启动 SSR 服务器。
`test`	使用 Jest 运行单元测试。
`test:lighthouse`	运行 Lighthouse 测试。
`test:max-file-size`	运行捆绑包大小测试。

您的项目带有两个用于质量保证的示例测试套件：使用 Jest 和 React 测试库创建的单元测试。

单元测试及其每个页面组件包含在各自的目录中。

要开始单元测试，请在终端中运行以下命令：

要了解有关测试网店的更多信息，请查看示例测试套件的源代码并浏览 Jest和 React 测试库的文档。

根据 Google 的 Lighthouse 测试套件衡量，Retail React App 从一开始就获得了出色的性能分数。使用以下脚本，我们可以在整个开发过程中轻松监控您的 Lighthouse 分数：

该脚本在您的网店运行 Lighthouse 三次，并将每个类别的中位数分数上传到 Google。然后，Google 使用这些分数来生成报告。脚本在退出之前会输出一个指向报告的链接。

要使用 Salesforce API 访问购物者数据，管理员必须完成设置 API 访问中描述的任务。

Retail React App 中的购物者数据通过构建在 commerce-sdk-isomorphic 客户端之上的类 CommerceAPI 来访问。您可以在 app/commerce-api/index.js 中自定义 CommerceAPI 类，并在 config/default.js 中对其进行配置。

CommerceAPI 类会自动注入每个页面的 getProps 方法中。例如，您可以如下从页面组件访问 API 包装程序：

CommerceAPI 包装程序当前为产品、促销、礼券和搜索使用 Commerce API。每个功能都提供了自己的一组端点，这些端点在 B2C Commerce API 参考中单独记录。

为了代表注册购物者和访客授权 API 请求，CommerceAPI 类依赖称为 Shopper Login and API Access Service (SLAS) 的 Salesforce Commerce API。

对于购物篮和订单，CommerceAPI 类还使用 Open Commerce API (OCAPI)。

设置 API 访问中介绍设置 Salesforce Commerce API（包括 SLAS）和 OCAPI 的说明。

Chakra UI 组件库是一种新的生产就绪技术，我们乐于在 Retail React App 中予以使用。它包括 50 多个用户界面组件，所有组件都具有出色的可访问性和可用性。可以使用样式道具或使用 JavaScript 对象来自定义组件以获得更高级的样式 (CSS-in-JS)。所有 Chakra 组件都带有精心设计的基本样式，这些样式能够用主题系统替代。

Chakra Theming 系统基于样式系统主题规范。您可以通过更新 app/theme 目录中的值来自定义组件的外观以适应您的品牌。

主题化可用于 app/components 大多数可重用组件，但不适用于“产品详细信息页面”或“产品列表页面”等页面。要更改这些页面的样式，请在源代码中为 app/pages 各自的页面组件编辑内联样式。

要在项目中包含自定义 SVG 图标，请将它们添加到 app/assets/svg 目录中，将它们导入 app/components/icons/index.js，然后按以下方式导出 React icon 组件：export const MyCustomIcon = icon('my-custom-icon')。

导入的 SVG 图标在构建时打包成 SVG sprite，并且 sprite 包含在服务器端渲染的 HTML 中。

PWA Kit React SDK 是支持 PWA Kit 网店的同构渲染管道的库。它包含许多为 Retail React App 提供支持的关键类、函数和组件。例如，启动整个渲染和路由过程的 app/ssr.js 中的 render() 函数是从 SDK 导入的。

SDK 抽出服务器端渲染、缓存和代理的一些实现细节，同时为您提供大量自定义其操作的机会。它还提供通用实用程序和工具，用于维护可以在客户端和服务器端呈现的单一代码集。

Salesforce 将 SDK 保持为与 Retail React App 分开的 npm 包，以便更轻松地进行改进。

PWA Kit React SDK 和整个 Retail React App 都是开源项目，可在 GitHub 上获得。我们欢迎来自 Commerce Cloud 社区的贡献！

本节中列出的开源技术是 Retail React App 最常用的技术。这些技术也最难以替代，我们选择它们不仅是因为其性能优异，还因为其出色的声誉。每一种技术都获得及时维护，而且高度可定制，文档丰富并被广泛使用。

以下是这些核心技术的简要概述，您可能已经熟悉其中的许多技术：

Babel编译您的 JavaScript 代码，使其与各种浏览器和 Node.js 环境兼容。Babel 转换高级语言句法并填充环境中缺少的任何功能。

Express 是一个流行的开源 Web 服务器框架，用 JavaScript 编写，在 Node.js 运行时环境中运行。Express.js 处理您定义为网店入口点的路由的 HTTP 请求。

Express 允许您配置常见的 Web 服务器设置，例如连接端口和返回响应的模板的位置。它还允许您在请求处理 Pipeline 中的任何位置添加额外的请求处理中间件。

PWA Kit 应用程序的所有服务器端代码都运行在 Node.js 上，Node.js 是 JavaScript 的开源运行时环境。运行时环境省略了特定于浏览器的 JavaScript API，并包含自己的 API，以跨平台的方式访问主机操作系统（例如文件系统）的功能。

Node.js 使用非阻塞或异步架构，非常适合构建高度可扩展和数据密集型的网店。

React是 Facebook 开发的一个框架，用于创建提供快速、流畅和沉浸式用户界面的单页应用程序。

在 React 应用程序中，用户界面由离散_组件_构建，这些组件通常排列在复杂的层次结构中。在设计良好的 React 应用程序中，每个组件只负责一项任务，而且通常该任务只是包含其他组件。

Retail React App 中的组件层次结构是为可扩展性而设计的。您可以在包含的组件基础之上构建或将它们换成新组件。

与 React 相关的软件包：

名称	说明
可加载组件	通过对较大的捆绑包进行代码拆分来提高性能。
ReactDOM	提供可在应用程序顶层使用的特定于 DOM 的方法。
ReactDOMServer	提供在服务器端预呈现 HTML 的方法 renderToString()。
React Helmet	帮助您管理对文档 `head` 标签的更改
React Router	将 URL 路径映射到 React 组件。路径可以表示为从最具体到最不具体的匹配模式。

Webpack 将您的代码整合到一个或多个捆绑包中。这些捆绑包被部署到 Managed Runtime，并最终作为水合过程的一部分加载到浏览器中。

Retail React App 从 PWA Kit React SDK 导入客户端和服务器端的现成 Webpack 配置。在大多数情况下，您无需更改这些配置，但如果要更改，可以在 webpack.config.js 扩展 Webpack 配置。

现在您已熟悉 Retail React App 的结构和内容，可以进行更深入的了解了！首先探索追踪代码，尤其是 app/pages 中的商务组件。
有关 Retail React App 和其他软件包中的最新文件的信息，请参阅 GitHub 存储库。