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 がどのように機能するかを理解するために、まずファイルの構造から見てみましょう。以下に、新しく生成されたプロジェクトのすべてのファイルとディレクトリを、簡単な説明とともにリストします。(説明で言及されているテクノロジーについては、このガイドの後の方で説明します。)

1.eslintignore                               Exclusion rules for ESLint
2.eslintrc.js                                Code style rules for ESLint
3.gitignore                                  Exclusion rules for git
4.prettierignore                             Exclusion rules for Prettier code formatting
5.prettierrc.yaml                            Code formatting rules for Prettier
6├── app/                                    Application code lives here
7    ├── assets/svg/                         SVG icon assets
8    ├── commerce-api/                       Commerce API client and hooks
9    ├── components/                         React components
10    │   ├── _app                            Root component
11    │   ├── _app-config                     Wrapper component for injecting custom code
12    │   └── _error                          Generic error component
13    │   └── ...
14    ├── constants.js                        Constants imported throughout the app
15    ├── contexts/                           React contexts
16    ├── hoc                                 Contains higher-order components
17    ├── hooks/                              React hooks
18    ├── main.jsx                            Client-side rendering entry point
19    ├── pages/                              Retail-oriented pages like home, PLP, and PDP
20    ├── partials/                           Partials imported throughout the app
21    ├── request-processor.js                Request processing functions (run at CDN edge)
22    ├── request-processor.test.js           Tests for request processing functions
23    ├── routes.jsx                          Maps request paths to route components
24    ├── routes.test.js                      Tests for mapping request paths to route components
25    └── ssr.js                              Server-side rendering entry point
26    ├── static/                             Static assets
27    │   └── manifest.json                   Manifest for PWA features like add to home screen
28    │   └── ...
29    ├── theme/                              Theme files for components
30    │   ├── components/
31    │   │   ├── base/                       Theme files for Chakra UI components
32    │   │   └── project/                    Theme files for custom components
33    │   ├── foundations/                    Frequently used theme values like colors and spacing
34    │   └── index.js
35    ├── translations/                       Translations for react-intl
36    ├── utils/                              Utilities imported throughout the app
37babel.config.js                             Transpilation rules for Babel
38cache-hash-config.json                      Cache breaking hash used by the CDN
39CHANGELOG.md                                Chronological list of changes to the template
40├── config/                                 Configuration files
41    ├── default.js                          Default configuration file
42    ├── mocks/                              Default configuration file with mock values for unit testing
43    └── sites.js                            Identifies sites configured in Business Manager. Includes localization details.
44jest-setup.js                               Unit testing setup for Jest
45jest.config.js                              Unit testing configuration for Jest
46LICENSE                                     Software licensing agreement
47node_modules/                               Package dependencies
48package-lock.json                           Package configuration lock file
49package.json                                Package configuration
50README.md                                   Basic documentation
51tests/                                      Unit tests
52worker/                                     Service worker

スクリプト

定期的な開発タスクを自動化するために、Retail React App にはいくつかのスクリプトが含まれています。これらのスクリプトをターミナルから実行するには、コマンド npm run <SCRIPT_NAME> を使用します。

以下に、付属しているすべてのスクリプトを、簡単な説明とともにリストします。

名前	説明
`analyze-build`	Production (本番) モードでプロジェクトをビルドし、2 つの 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 inspector を使用して SSR サーバーを起動します。
`start:pseudolocale`	疑似地域情報を使用して SSR サーバーを起動します。
`test`	Jest を使用してユニットテストを実行します。
`test:lighthouse`	Lighthouse テストを実行します。
`test:max-file-size`	バンドルサイズのテストを実行します。

テストスイート

プロジェクトには、Jest によって作成されたユニットテストと、React Testing Library (React テストライブラリ) という、品質保障のための 2 つのテストスイートの例が付属しています。

ユニットテストは、各ページコンポーネントとともに、対応するディレクトリに含まれています。

ユニットテストを開始するには、ターミナルで以下のコマンドを実行します:

1npm run test

ストアフロントのテストの詳細については、テストスイートのサンプルのソースコードを確認し、Jest と React Testing Library のドキュメントを参照してください。

Google の Lighthouse テストスイートでの測定によれば、Retail React App は最初から良好なパフォーマンススコアを上げています。以下のスクリプトを使用すれば、開発中を通じて Lighthouse スコアを簡単にモニターできます:

1npm run test:lighthouse

このスクリプトはストアフロントで Lighthouse を 3 回実行し、各カテゴリの中央値を Google にアップロードします。その後 Google はこれらのスコアを使用して、レポートを生成します。レポートへのリンクは、スクリプトによって終了前に出力されます。

Salesforce API

Salesforce API を使用して買い物客データにアクセスするには、管理者が API アクセスの設定に説明されているタスクを完了する必要があります。

Note

Retail React App の買い物客データは、commerce-sdk-isomorphic クライアントを基盤として構築された CommerceAPI という名前のクラスを通じてアクセスできます。CommerceAPI クラスは app/commerce-api/index.js でカスタマイズし、config/default.js で構成できます。

CommerceAPI クラスは各ページの getProps メソッドに自動的に挿入されます。たとえば、以下のようにページコンポーネントから API ラッパーにアクセスできます:

1const MyPage = (props) => {
2  const {categories} = props
3  return <div>There are {categories.length} categories.</div>
4}
5
6MyPage.getProps = async ({api}) => {
7  categories = await api.shopperProducts.getCategory({
8    parameters: {id: categoryId, levels: 0}
9  })
10
11  return {categories}
12}

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

Chakra UI コンポーネントライブラリは即実戦可能な新しいテクノロジーであり、当社ではこのコンポーネントライブラリを Retail React App に採用しています。このライブラリは 50 以上のユーザーインターフェイスコンポーネントを含んでおり、いずれもアクセシビリティとユーザビリティに優れています。コンポーネントは style props でカスタマイズでき、より高度なスタイル設定のために JavaScript オブジェクトを使用することもできます (CSS-in-JS)。すべての Chakra コンポーネントには適切に設計されたベーススタイルがあり、テーマ設定システムで上書きできます。

テーマ設定

Chakra のテーマ設定システムは、Styled System テーマ仕様に基づいています。コンポーネントの外観と使用感は、app/theme ディレクトリで値を更新することで、ブランドに合わせてカスタマイズできます。

テーマ設定は、app/components の再利用可能なコンポーネントのほとんどで使用できますが、商品情報ページや商品一覧ページなどのページでは使用できません。これらのページのスタイルを変更するには、app/pages の対応するページコンポーネントでソースコードのインラインスタイルを編集します。

Note

SVG アイコン

プロジェクトにカスタムの SVG アイコンを含めるには、アイコンを app/assets/svg ディレクトリに追加し、app/components/icons/index.js にインポートし、React icon コンポーネントを export const MyCustomIcon = icon('my-custom-icon') のようにしてエクスポートします。

インポートした SVG アイコンは、ビルド時に SVG スプライトにパッケージ化され、サーバー側でレンダリングされる HTML にこのスプライトが含められます。

PWA Kit React SDK

PWA Kit React SDK は、PWA Kit ストアフロントのアイソモーフィックレンダリングパイプラインをサポートするライブラリです。Retail React App を駆動する多くの主要なクラスや関数、コンポーネントが含まれています。たとえば、レンダリングとルーティングのプロセス全体を開始する app/ssr.js の render() 関数は、この SDK からインポートされます。

SDK は、サーバー側レンダリング、キャッシング、およびプロキシの実装情報を抽象化する一方で、操作をカスタマイズするための多くの機会を提供します。また、クライアント側とサーバー側の両方でレンダリングできる 1 つのコードセットを管理するために、一般的な用途のユーティリティとツールが用意されています。

Salesforce では、より簡単に改善を行えるように、SDK を Retail React App とは独立した npm パッケージとして管理しています。

PWA Kit React SDK と Retail React App 全体はオープンソースプロジェクトであり、GitHub から入手可能です。Commerce Cloud コミュニティの貢献をお待ちしています。

その他のコアテクノロジー

このセクションにリストするオープンソーステクノロジーは、Retail React App でもっとも頻繁に使用されているものです。これらはまた、他の代替テクノロジーで置き換えることが困難なもので、当社ではこれらをパフォーマンスだけでなく、定評に基づいて選択しています。いずれもアクティブに管理が行われており、高度なカスタマイズが可能なうえ、良好なドキュメントが提供されており、幅広く使用されています。

以下はこれらのコアテクノロジーの概要です。多くのものはおそらくすでにおなじみのものでしょう:

Babel

Babel は JavaScript コードをコンパイルして、広範囲のブラウザーや Node.js 環境と互換性をもつようにします。高度な言語構文を変換し、環境で欠如している機能をポリフィルします。

Express.js

Express は広範に使用されているオープンソースの Web サーバーフレームワークです。JavaScript で記述され、Node.js ランタイム環境で実行します。また、ストアフロントへのエントリポイントとして定義するルートの HTTP リクエストを処理します。

Express では、接続ポートや、レスポンスを返すためのテンプレートの場所など、一般的な Web サーバー設定を構成できます。また、リクエスト処理パイプラインの任意のポイントで、追加のリクエスト処理ミドルウェアの追加を可能にします。

Node.js

PWA Kit アプリケーションのすべてのサーバー側コードは、JavaScript のオープンソースランタイム環境である Node.js 上で実行されます。このランタイム環境は、ブラウザー固有の JavaScript API を省略し、ホストオペレーティングシステム (ファイルシステムなど) の機能にクロスプラットフォームでアクセスするための独自の API を含んでいます。

Node.js は非ブロック、または非同期のアーキテクチャを使用します。これは拡張性が高く、多量のデータを使用するストアフロントの構築にとって理想的なものです。

React

React は、高速で流動的、かつ没入型のユーザーインターフェイスを実現するシングルページアプリケーションを作成するために Facebook によって開発されたフレームワークです。

React アプリでは、ユーザーインターフェイスは通常、複雑な階層をもつ個別の コンポーネント で作成されます。適切に設計された React アプリでは、各コンポーネントは 1 つのジョブに対してのみ責任を負います。多くの場合そのジョブは、他のコンポーネントを含むためのものです。

Retail React App のコンポーネント階層は、拡張性を考慮して設計されています。含まれているコンポーネントを基盤として作成するか、これらのコンポーネントを新しいコンポーネントと交換できます。

React に関連するパッケージ:

名前	説明
読み込み可能なコンポーネント	大規模なバンドルのコードを分割して、パフォーマンスを改善します。
ReactDOM	アプリケーションの最上位レベルで使用可能な DOM 特定のメソッドを提供します。
ReactDOMServer	HTML をサーバー側で事前にレンダリングするメソッド renderToString() を提供します。
React Helmet	ドキュメントの `head` タグへの変更の管理を支援します。
React Router	URL パスを React コンポーネントにマッピングします。パスは、非常に特定のものからあまり特定でないものまでに一致するパターンとして表現できます。

Webpack

Webpack はコードを 1 つまたは複数のバンドルにまとめます。これらのバンドルは Managed Runtime にデプロイされ、最終的にはハイドレーションプロセスの一環としてブラウザーに読み込まれます。

Retail React App は、PWA Kit React SDK からクライアント側とサーバー側の既製の Webpack 構成をインポートします。ほとんどの場合これらの構成を変更する必要はありませんが、変更する場合は、webpack.config.js で Webpack 構成を拡張できます。

次のステップ

これで Retail React App の構造とコンテンツについて理解できたので、さらに掘り下げて学習しましょう。ソースコード、特に app/pages の e コマースコンポーネントについての理解を深めてください。
Retail React App やその他のパッケージの最新ファイルについては、GitHub リポジトリを参照してください。