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 (本番) モードでプロジェクトをビルドし、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 つのテストスイートの例が付属しています。

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

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

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

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

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

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

Retail React App の買い物客データは、commerce-sdk-isomorphic クライアントを基盤として構築された CommerceAPI という名前のクラスを通じてアクセスできます。CommerceAPI クラスは app/commerce-api/index.js でカスタマイズし、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 スプライトにパッケージ化され、このスプライトがサーバー側でレンダリングされる HTML に含められます。

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

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

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

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

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

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

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

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

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

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

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

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

これで Retail React App の構造とコンテンツについて理解できたので、さらに掘り下げて学習しましょう。ソースコード、特に app/pages の e コマースコンポーネントについての理解を深めてください。