Retail React App

Retail React App 是一組範例程式碼和工具，設計來讓您開始著手在 API 之上建置網店，並將其代管在 Managed Runtime 上。這份架構指南說明了 Retail React App 的架構和內容，並強調了其彈性、開源的基礎。

所有 PWA Kit 專案皆以相同的一組檔案開始。在專案一開始，這些檔案透過執行指令碼而產生。(此流程於開始使用指南中有完整說明。)

若要大致瞭解 Retail React App 的運作方式，請從探索其檔案架構開始。以下是新產生專案的所有檔案和目錄，以及相關的簡短描述。(描述中提及的技術將於這份指南稍後進一步說明。)

為了自動化例行開發任務，Retail React App 包含了幾個指令碼。使用 npm run <SCRIPT_NAME> 命令在終端機內執行。

以下是所有包含的指令碼完整清單，以及相關描述：

名稱	描述
`analyze-build`	在 Production 模式中建置專案，並建立兩個 webpack-bundle-analyzer 報告。使用報告來監控您的程式碼套件大小。
`compile-messages`	將所有已當地語系化的訊息編譯為 AST 格式。
`extract-messages`	自動從 React 元件中提取預設地區設定的訊息。
`format`	使用 Prettier 格式化程式碼。
`lint`	使用 ESlint 尋找不一致的程式碼樣式。
`lint:fix`	自動修正 ESlint 錯誤。
`prod:build`	在 Production 模式中建置專案。
`push`	推送程式碼套件 (Production 建置成品) 至 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`	執行 bundlesize 測試。

您的專案擁有兩個範例測試套件以進行品質保證：透過 Jest 和 React Testing Library 建立的單元測試。

單元測試包含在各自目錄中的每個頁面元件旁邊。

若要開始單元測試，請在您的終端機中執行以下命令：

想進一步瞭解網店測試，請查看範例測試套件的原始程式碼，並探索 Jest 和 React Testing Library 的文件。

一開始，Google 的 Lighthouse 測試套件就為 Retail React App 測出了傑出的效能分數。使用以下指令碼，我們可以在整個開發過程中輕鬆監控您的 Lighthouse 分數：

指令碼會在您的網店上執行 Lighthouse 三次，並將每個類別的中位數分數上傳至 Google。接著，Google 會使用這些分數來產生報告。指令碼在退出之前會輸出報告連結。

若要使用 Salesforce API 來存取購物者資料，管理員必須完成設定 API 存取中說明的任務。

Retail React App 中的購物者資料可透過稱為 CommerceAPI 的類別來存取，建置於 commerce-sdk-isomorphic 用戶端上。您可以在 app/commerce-api/index.js 中自訂 CommerceAPI 類別，並在 app/api.config.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)。

設定 Salesforce Commerce API (包括 SLAS) 和 OCAPI 的指示已在設定 API 存取中詳細說明。

Chakra UI 元件資產庫是一種可立即投入生產的新技術，我們迫不及待要在 Retail React App 中使用它了。其包含了 50+ 使用者介面元件，都擁有傑出存取性和可用性。可使用 Style Props 自訂元件，或使用 JavaScript 物件進行進階樣式修改 (CSS-in-JS)。所有 Chakra 元件都擁有設計良好的基本樣式，可用主題系統覆寫。

Chakra 主題系統是以 Styled System 主題規格為基礎。您可以更新 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 網店同構轉譯 Pipeline 的資產庫。其中包含許多為 Retail React App 提供支援的關鍵類別、函式、元件。例如，在 app/ssr.js 中啟動整個轉譯和路由過程的 render() 函式是從 SDK 匯入的。

SDK 為伺服器端轉譯、快取、Proxy 處理摘取部分實作詳細資訊，同時為您提供許多機會自訂這些操作。它還提供一般用途的公用程式及工具，用於維護可以在用戶端和伺服器端轉譯的單一組程式碼。

Salesforce 將 SDK 維護為與 Retail React App 分開來的 npm 套件，好讓改善過程更容易。

PWA Kit React SDK 和整個 Retail React App 都是開源專案，可於 GitHub 取得。歡迎來自 Commerce Cloud 社群的貢獻！

此章節所列出的開源技術是 Retail React App 最常使用的技術。它們同時也是最難以其他方式取代的，因此我們不僅因為這些技術的成效特色選擇它們，也是因為它們的知名程度。每一項技術都受到積極維護、高度自訂化、擁有詳細說明文件，也受到廣泛使用。

以下是每項核心技術的簡短介紹，您可能已經對其中幾項相當熟悉：

Babel 可編譯您的 JavaScript 程式碼，使之與各種瀏覽器和 Node.js 環境相容。此技術會轉換進階語言語法，並 polyfill 環境中缺少的任何功能。

Express 是熱門的開源網頁伺服器架構，以 JavaScript 編寫，並在 Node.js 執行階段環境中執行。此技術可處理您定義為網店進入點路由的 HTTP 要求。

Express 讓您能夠進行常見的網頁伺服器設定，例如連線通訊埠和傳回回應的範本位置。也讓您能在要求處理 Pipeline 中的任何位置，新增額外的要求處理中介軟體。

PWA Kit 應用程式的所有伺服器端程式碼均在 Node.js 上執行，這是 JavaScript 的開源執行階段環境。執行階段環境省略了瀏覽器特定的 JavaScript API，並包含其自有的 API，以跨平台的方式存取主機作業系統 (例如檔案系統) 的功能。

Node.js 使用非封鎖或非同步架構，非常適合建置擴展性高、資料密集型的網店。

React 是由 Facebook 開發、用於建立單頁式應用程式的架構，可傳遞快速、流暢的沈浸式使用者介面。

在 React 應用程式中，使用者介面會以個別的「元件」建置，這些元件通常以複雜的階層安排。在設計良好的 React 應用程式中，每個元件僅負責一項工作，而那項工作通常只是包含其他元件而已。

Retail React App 的元件階層是專為擴充性而設計。您可以在內含元件的基礎上建置，或將之替換成新的元件。

React 相關套件：

名稱	描述
Loadable Components	對較大型的套件進行程式碼分割來提高效能。
ReactDOM	提供 DOM 特定方法，可用於應用程式的最高層級。
ReactDOMServer	提供 renderToString() 方法，在伺服器端預先轉譯 HTML。
React Helmet	協助您管理文件的`head` 標記變更。
React Router	對應 URL 路徑至 React 元件。路徑能以模式表達，從最特定到最不特定進行比對。

Webpack 將您的程式碼整合為一或多個套件。這些套件會部署至 Managed Runtime，最終作為 Hydration 流程的一部分載入瀏覽器。

Retail React App 為用戶端和伺服器端從 PWA Kit React SDK 匯入現成的 Webpack 設定。在大部分情況中，您不需要變更這些設定，但您若作出變更，可在 webpack.config.js 中擴充 Webpack 設定。

這樣您就已經熟悉 Retail React App 的架構和內容了，讓我們繼續深入探討吧！請先從探索原始程式碼開始，特別是 app/pages 中的電子商務元件。