ローカル環境の設定

このガイドでは、PWA Kit を使用した開発のためにローカル環境を設定する方法を説明します。

PWA Kit での開発には、以下のような Unix ベースのオペレーティングシステムを使用することを推奨します。

Windows ユーザー: Microsoft による Node デベロッパーのための 公式の推奨事項を参照してください。

Managed Runtime でサポートされている特定のバージョンの Node と Node Package Manager (NPM) をインストールする必要があります。

Node 18.x ダウンロードページ に移動して、お使いのマシンに合ったインストーラーをダウンロードします。

Windows ユーザー: 自分のプロセッサーに対応する .msi ファイルをダウンロードします。たとえば、64 ビットの Intel プロセッサーを使用している場合は、x64 のインストーラーを選択します。

Mac ユーザー: .pkg ファイルをダウンロードします。

Apple Silicon ユーザー: Rosetta をまだインストールしていない場合は、softwareupdate --install-rosetta を実行します。

Linux ユーザー: 自分のプロセッサーに対応する -linux ファイルをダウンロードします。たとえば、64 ビットの Intel プロセッサーを使用している場合は、好みのアーカイブ形式の linux-x64 インストーラーを選択します。

適切な Node インストーラーをダウンロードしたら、インストーラーを開いてセットアップの手順を完了します。

インストーラーで確認を求められたら、デフォルトのオプションを選択して、Node.js runtime のインストール、Node Package Manager のインストール、およびパスへの Node.js runtime の追加も行います。

作業を進める前に、正しいバージョンの Node と NPM がインストールされていることを確認します。

  1. ターミナルを開きます。
  2. node -v を実行します。
  3. v18.16.1 (または最新の 18.x バージョン) が返されることを確認します。
  4. npm -v を実行します。
  5. 9.5.1 (または Node 18.x に含まれる最新バージョン) が返されることを確認します。

異なるバージョンの NPM がインストールされている場合は、バージョン 9.5.1 を以下のように手動でインストールできます。

  1. ターミナルを開きます。
  2. npm install -g npm@9.5.1 を実行します。
  3. npm -v を再度実行します。
  4. 9.5.1 が返されることを確認します。

Node の複数のバージョンを Windows で管理したい場合は、Node Version Switcher または Volta をお勧めします。Corey Butler の Node Version Manager (NVM) for Windows は、当社によるテスト中に問題が発生したため、お勧めしません。

Mac と Linux のユーザーには、Node Version Manager のインストールをお勧めします。

各 PWA Kit ストアフロントでは、デプロイを管理するために、Runtime Admin で作成されたプロジェクトをもつ必要があります。

Managed Runtime と Runtime Admin を使用する前に、それらの機能を有効にし、アクセスをリクエストする必要があります。組織で Managed Runtime と Runtime Admin を有効にするには、Salesforce アカウントチームにお問い合わせください。アクセスするには、Commerce Cloud 管理者に連絡し、Account Manager を使用して Managed Runtime User または Managed Runtime Admin のいずれかの役割をアカウントに追加するよう依頼してください。

まだ Runtime Admin でプロジェクトが作成されていない場合は、以下の手順に従います。

  1. Runtime Admin にログインします。
  2. New Project (新規プロジェクト) をクリックします。
  3. プロジェクトの名前を入力します。
  4. Create Project (プロジェクトの作成) をクリックします。

プロジェクト ID を書き留めてください。開発用のプロジェクトファイルを生成する際に必要になります

最初にプロジェクトを作成する場合、必要なクラウドインフラストラクチャをデプロイするまでは、サイトに Web でアクセスすることはできません。このデプロイプロセスには最大 40 時間かかることがあります。

Runtime Admin で可能な操作の詳細については、Managed Runtime の管理 のガイドを参照してください。

ほとんどの PWA Kit デベロッパーは、以前に生成したプロジェクトファイルを含むリポジトリをクローンすることから始めます。(新規プロジェクトの生成方法については、次のセクションに進んでください。)

プロジェクトリポジトリをクローンしたら、パッケージの依存関係をインストールする必要があります。

  1. ターミナルを開きます。
  2. プロジェクトディレクトリに変更します。
  3. npm ci を実行します。

すでに既存の PWA Kit プロジェクトがあり、前のセクションの手順を完了している場合は、次のセクションに進んでください。それ以外の場合は、プロジェクトを生成する必要があります。

プロジェクトを生成するには、ターミナルを開いて以下のコマンドを実行します。~/PLACEHOLDER-PROJECT-ID は、Runtime Admin からのプロジェクト ID を含むパスに置き換えてください。

npx コマンドの @latest を、@v3.0.0@v2.7.3 など、Retail React App の特定のバージョンに置き換えることができます。バージョンを指定しない場合、古いバージョンのキャッシングが原因で予期しない結果が生じる場合があります。

プロジェクトのプリセットを選択するように求められたら、次のいずれかのオプションを選択します:

  • retail-react-app-demo: Retail React App ストアフロントテンプレートを使用し、バックエンドにはデモの Sandbox (サンドボックス) を使用します。追加の構成は必要ありません。
  • retail-react-app: Retail React App ストアフロントテンプレートを使用し、バックエンドには独自の B2C Commerce インスタンスを使用します。構成値を入力する必要があります。

retail-react-app プリセットを使用する場合、生成スクリプトによっていくつかの構成値の入力を求められます。これらの構成値によって、新しい PWA Kit プロジェクトが Runtime Admin ツールと B2C Commerce インスタンス内の対応プロジェクトに関連付けられます。

以下の表は、各プロジェクト構成値とその場所を示しています。構成値の詳細については、B2C Commerce API ドキュメントでも説明しています。ベース URL とリクエストの作成を参照してください。

構成値詳細
Managed Runtime Admin のプロジェクト IDManaged Runtime の管理で、プロジェクトの作成方法と、既存のプロジェクトのプロジェクト ID を検索する方法を説明しています。
  • 例: example-project
B2C Commerce インスタンスの URL開発やテストのために新しい B2C Commerce インスタンスが必要な場合は、On-Demand Sandbox の作成を参照してください。
  • 例: https://zzdc-001.dx.commercecloud.salesforce.com
Commerce API クライアント IDこの識別子は Account Manager では現在使用されていません。API アクセス用のクライアント ID の生成を参照してください。
  • 例: 1adba44c-ee9b-41f9-b4bf-1bbc3dda1967
Commerce API プライベートクライアントモードこれにより、アプリケーションで買い物客のログインにパブリック認証フローとプライベート認証フローのどちらを使用するかを切り替えます。詳細については、Shopper Login のドキュメントおよびSLAS プライベートクライアントの使用を参照してください。
  • デフォルト: true
Business Manager のサイト ID特定の eコマースサイトを識別するために使用される文字列。Business Manager で利用可能なサイトと、関連付けられているサイト ID のリストを取得するには、管理 > サイト > サイトの管理の順に移動します。
  • 例: RefArch
Business Manager の Commerce API 組織 IDレルムとインスタンスに基づいて、API アクセス用に組織を識別するために使用される文字列。Business Manager で組織 ID を見つけるには、管理 > サイトの開発 > Salesforce Commerce API 設定の順に移動します。
  • 例: f_ecom_zzdc_001
Business Manager の Commerce API ショートコードルーティングのためにレルムに割り当てられた 8 文字の文字列。ショートコードはすべてのインスタンスにわたり、レルム全体に適用されます。(すべての On-Demand Sandbox のショートコードは kv7kzm78 です)。Business Manager でショートコードを見つけるには、** 管理** >** サイトの開発** > Salesforce Commerce API 設定 の順に移動します。
  • 例: kv7kzm78
Einstein Configurator の API クライアント IDCommerce Cloud デベロッパーと Einstein Configurator への直接のアクセスについては、Einstein API のドキュメントを参照してください。

プロジェクトの生成後、生成されたプロジェクトファイルをリポジトリにコミットし、そのリポジトリをストアフロントのデベロッパーと共有することをお勧めします。

プロジェクトの構成値は、プロジェクトを生成した でも変更できます。詳しくは、構成ファイルを参照してください。

別の B2C Commerce インスタンスを使って作業するためにプロジェクトファイルをカスタマイズした場合など、これらの値を変更した後は、構成を更新することを忘れないでください。

ローカル開発のために Web サーバーを起動するには、プロジェクトディレクトリから以下のコマンドを実行します:

開発サーバーが実行されたら、ブラウザーを開いてストアフロントをプレビューできます:

開発サーバーは、キーボードショートカット Control+C を使用していつでも停止できます。

サーバー側でレンダリングされるページをプレビューするには、プレビューしたい URL の最後に ?__server_only のクエリ文字列を追加します。たとえば、URL www.example.com?__server_only を訪問することで、www.example.com のサーバー側レンダリングバージョンをテストできます。

  • 既存のプロジェクトをクローンして npm ci を実行した後、または新規プロジェクトを生成した後に、ターミナルにアクティビティが表示されるまで数分かかることがあります。プロセスが完了するまでキャンセルしないでください。また、アンチウィルスソフトウェア (特に Windows を使用している場合) によって、インストールに通常よりも長い時間がかかることがあります。

  • authorize エンドポイントから HTTP 401 エラーレスポンスが返された場合は、Shopper Login and API Access Service (SLAS) に構成の問題があります。SLAS 構成を修正するには、API アクセスの設定の手順を参照してください。