構成ファイル

構成ファイルを使用すると、PWA Kit アプリケーションの動作に関する多数の要素 (API アクセス、URL の書式設定、複数サイトの処理、リクエストのプロキシ、サーバー側でのレンダリングなど) をカスタマイズできます。

構成ファイルは、JavaScript、YAML、JSON のいずれかを選択して記述できます。対応するファイル拡張子は .js、.yml、.yaml、.json です。

Retail React App テンプレートで PWA Kit プロジェクトを作成すると、1 つの構成ファイル app/config/default.js が付随します。エクスポートする構成オブジェクトは pwa-kit-create-app に渡されたオプションに基づいて設定されますが、その構成はいつでも更新できます。最初のプロジェクト生成後に、B2C Commerce インスタンスの変更に合わせて更新が必要になることがよくあります。

アイソモーフィックレンダリングをサポートするために、構成値はページにシリアル化されます。構成の中にシークレットを含めないでください。

PWA Kit は環境固有の構成をサポートしているので、default.js を置き換えたり、追加の構成ファイルで補完したりできます。これについては、このガイドで後ほど説明します。

まず、default.js または任意の構成ファイルで利用可能な、特定の構成オブジェクトとプロパティについて見てみましょう。

アプリケーションと Managed Runtime を関連付けるプロジェクト文字列は、構成ファイルの一部ではなく、プロジェクトディレクトリのルートにある package.json ファイルの先頭の name プロパティにあります。最初のプロジェクト生成後に、Runtime Admin で表示されるプロジェクト ID に合わせて name の値を変更できます。

1.5.0 より古いバージョンの PWA Kit では、この設定は app/api.config.js にあります。

B2C Commerce API および Open Commerce API (OCAPI) へのアクセスを構成するには、構成ファイルからエクスポートされる app.commerceAPI オブジェクトを編集できます。

注釈付きコードスニペットと値の例を以下に示します。

Einstein API へのアクセスを構成するには、app.einsteinAPI オブジェクトを編集します。

注釈付きコードスニペットと値の別の例を以下に示します。

上記のコードのスニペットで構成オブジェクト使用する CommerceAPI クラスの詳細については、Retail React App のアーキテクチャガイドを参照してください。

B2C Commerce インスタンスの API アクセスを可能にする Account Manager と Business Manager の設定タスクの詳細については、API アクセスの設定のガイドを参照してください。

ストアフロントの URL の書式設定は、app.url オブジェクトでカスタマイズできます。

app.url オブジェクトは、デフォルトで以下の値で構成されています。

このデフォルト設定では、現在のサイトと地域情報の両方が URL パスに表示されます。

url.locale に次の値のいずれかを設定することで、現在の地域情報が URL にどのように表示されるか (または表示されないか) を選択できます。

path: 地域情報は URL パスに含められます。例: /en-US/women/dress
query_param: 地域情報はクエリパラメーターとして含められます。例: /women/dress?locale=en-US
none: 地域情報は URL に含められません。例: /women/dress

url.showDefaults: このブール値で、デフォルトのサイトまたは地域情報の値を URL に表示するかどうかを決定します。デフォルトは false です。

アプリケーションに構成されたサイトを、config/sites.js という独自のファイルに抽出します。このファイルは各構成ファイルにインポートされ、app オブジェクト内にエクスポートされます。このようにファイルを分けることで、アプリケーションでサポートされているサイトと Business Manager バックエンドで定義されているサイトの同期がより簡単になります。(必要に応じて、構成ファイルでサイトを直接定義することもできます。)

app オブジェクトには、複数のサイトとそのエイリアスを管理するためのその他の設定も含まれています。これらの設定は、複数サイトのガイドでより詳しく説明しています。

リクエストのプロキシは、ssrParameters.proxyConfigs 配列で設定します。詳しくは、リクエストのプロキシのガイドで説明しています。

1.5.0 より古いバージョンの PWA Kit では、この設定は package.json にあります。

次の表は、サーバー側のレンダリングに関連する構成オプションの概要を示しています。これらのオプションは app オブジェクトの一部ではなく、メインの exports オブジェクトの個々のプロパティとして表現されます。

プロパティ	説明
`ssrParameters.ssrFunctionNodeVersion`	アプリケーションサーバーの実行に使用する Node のバージョンを決定する文字列。許可値: `16.x`。
`ssrEnabled`	サーバー側のレンダリングに必要なファイルの作成を有効または無効にするブール値。この値を `false` に設定することは、2021 年 8 月をもって廃止されました。
`ssrOnly`	グロブ式の配列。ここで `` はワイルドカードで、ゼロ以上の任意の文字のインスタンスと一致します。サーバー側レンダリングシステム専用であり、かつ、`/mobify/bundle/` パスでは使用できないファイルを決定します。新しく生成されたプロジェクトのデフォルト: `['ssr.js', 'ssr.js.map', 'node_modules//.*']`
`ssrShared`	グロブ式の配列。ここで `` はワイルドカードで、ゼロ以上の任意の文字のインスタンスと一致します。サーバー側レンダリングシステムで使用でき* 、かつ、`/mobify/bundle/` パスで使用可能なファイルを決定します。新しく生成されたプロジェクトのデフォルト:

app/config/ ディレクトリには、特定の環境用の構成ファイルなど、複数の構成ファイルを含めることができます。

環境固有の構成を使用することで、デプロイをより効率的かつ柔軟に行えます。たとえば、以下が可能です:

1 つのバンドルを複数の Managed Runtime 環境にデプロイし、各環境をそれぞれ異なる B2C Commerce インスタンスに接続する。
ローカル開発時には自社用の On-Demand Sandbox (サンドボックス) に接続するが、Managed Runtime にデプロイする場合は異なるインスタンスに接続する。

環境固有の構成ファイルを作成するには、default.js で使用したものと同じ規則に従いますが、ファイルのベース名としてターゲット環境の名前を使用します。サポートされているいずれかのファイル形式とそれに対応する拡張子を使用します。例: production.js、staging.json。

PWA Kit アプリケーションは、app/config を検索して以下の順序で質問をすることで、読み込むべき正しい構成ファイルを選択します。

Managed Runtime 上で現在動作している環境名と一致するファイルはありますか。
ローカルで動作している場合、サポートされているファイル拡張子をもつ local というファイルはありますか。
構成ファイルが見つからなかった場合、サポートされているファイル拡張子をもつ default というファイルはありますか。

これらの質問の答えが「はい」になると、PWA Kit は検索を中止し、対象となるファイルを読み込みます。

2 つのファイルのベースネームが同じだがファイル拡張子が異なる場合、最も高い優先順位が割り当てられているファイル拡張子が選択されます。サポートされているファイル拡張子の優先順位割り当ては、高いものから順に .js、.yml、.yaml、.json となっています。つまり、default.js と default.json では、default.js の方が優先順位が高いので、PWA Kit はそちらを読み込むことになります。