v3 へのアップグレード

v3 では、@salesforce/retail-react-app を npm 依存関係として追加し、プロジェクトで拡張テンプレートを有効にすることで、@salesforce/retail-react-app の更新を利用できるようになりました。

このガイドでは、PWA Kit プロジェクトを v2.7.x から v3.0.0 に更新する方法について説明します。

PWA Kit v3 では、以下を含む多くの新機能が追加されました。

⚛️ 必須:

  • getProps の破壊的変更 (breaking change)
  • React 18、Node 18、Chakra 2 などのサポートを含む、主要なライブラリの更新

🔨 オプション: 拡張テンプレート — プロジェクトのコード占有領域を大幅に削減し、開発の手間、所有コスト、そして将来のアップグレードに関する問題を軽減します。詳細については、テンプレートの拡張性のガイドを参照してください。

🪝 オプション: @salesforce/commerce-sdk-react "hooks" の統合 — API 呼び出しをプロジェクトの実装から分離することにより、API 呼び出しを npm ライブラリとの依存関係としてアップグレードできるようにします。これにより、TanStack クエリを介して多くの優れた機能 (状態管理などを含む) がもたらされます。開始するには、Commerce SDK React ドキュメントをご覧ください。

PWA Kit SDK は、@salesforce NPM 組織に移動されました。v3 にアップグレードするには、新しいパッケージをインストールし、次のパッケージのすべての import ステートメントを置き換えます。

  • pwa-kit-react-sdk -> @salesforce/pwa-kit-react-sdk@^3
  • pwa-kit-runtime -> @salesforce/pwa-kit-runtime@^3
  • pwa-kit-dev -> @salesforce/pwa-kit-dev@^3
  • pwa-kit-create-app -> @salesforce/pwa-kit-create-app@^3
  • retail-react-app -> @salesforce/retail-react-app@^3

v3.0.0 以降、PWA Kit では withReactQuery という新しいデータフェッチ戦略が導入されています。この戦略は react-query ライブラリを使用し、React フックを記述してデータを同型で取得できるようにします。getProps とは異なり、クライアント側とサーバー側のデータ取得ロジックを複製する必要がなくなりました。このバージョンでは、デフォルトで、@salesforce/retail-react-app は react-query を利用した @salesforce/commerce-sdk-react を使用します。

  • withReactQuery と withLegacyGetProps は両方同時に使用できます。
  • getProps と shouldGetProps は Retail React App ページのデフォルトテンプレートから削除されましたが、廃止予定ではありません。これらのメソッドは引き続き長期的にサポートされます。

以下に示すように、package.json の依存関係を変更します。peerDependencies から @chakra-ui/system を削除し、dependencies または devDependencies に含めます。

Node 18 と npm 9 をサポートするように package.json のエンジンを更新します。

npm i を使用してプロジェクトの依存関係を再インストールします。

v2.7.x から v3.x に移行する場合、拡張テンプレートを使用するかどうかを選択できます。この機能を利用するには、@salesforce/retail-react-app (または将来的には別の拡張可能なテンプレート) から少なくとも 1 つのファイルをインポートする必要があります。

そこから、npx pwa-kit-create-app@2.x を介して生成した元のプロジェクトから変更したファイルの数を検討します。一部のお客様は大量 (おそらく数百) のファイルを所持していますが、その場合でも、かなりの数が変更されない可能性があります。これらの未変更ファイルは @salesforce/retail-react-app からインポートするのに適した候補ですが、このプロセスを慎重かつ段階的に実行することをお勧めします。@salesforce/retail-react-app の多くのファイルは類似していますが、PWA Kit Retail React App の v2.x の以前の状態から変更されています。特に、@salesforce/commerce-sdk-react の統合 (移行の詳細については後で詳述) により、インポートおよびファイル構造の点で多数のファイルが変更され、commerce-api ディレクトリ全体が Retail React App から削除されました。

拡張テンプレートを利用するためにプロジェクトを移行する場合、PWA Kit SDK のバージョン 2.x と npx pwa-kit-create-app@2.x によって生成されたプロジェクトは @salesforce/commerce-sdk-react に依存していないのに対し、新しいコード @salesforce/retail-react-app@^1.x はこのライブラリを頻繁に使用し、多くのファイルに触れて変更することに注意してください。変更の規模を把握するには、この Github の差分 https://github.com/SalesforceCommerceCloud/pwa-kit/compare/release-2.7.x...release-3.0.x?diff=unified#files_bucket で release-2.7.x → release-3.0.x を比較し、@salesforce/commerce-sdk-react を検索して、このインポートを追加するすべての追加内容を確認してください。

アプリがバージョン 2.x (app/commerce-api ディレクトリを含む) とコードを共有しようとすると、そのコードが commerce-api フォルダーと @salesforce/commerce-sdk-react npm モジュールの両方に (2 つの非常に異なる形式で) 存在しているバンドルに、不要なコードを追加するリスクがあります。

v3.0.0 以降、PWA Kit は withReactQuery という別のフェッチ戦略を使用します。この戦略は、react-query ライブラリを活用し、SSR レンダリングパスでのクエリを有効にします。@salesforce/retail-react-app は、react-query を利用した @salesforce/commerce-sdk-react を使用します。

フックがサーバー側で機能するには、AppConfig コンポーネントを新しい高階コンポーネント withReactQuery でラップする必要があります。

デフォルトのフェッチ戦略としての ReactQuery への移行の一環として、@salesforce/retail-react-app@^1 では、レガシーの getProps() 呼び出しが引き続き機能することを保証するための変更が必要です。

上記の依存関係のアップグレードを完了すると、以下のライブラリに関連する問題がプロジェクトで発生する可能性があります。以下のセクションでは、これらの問題を解決するためのソリューションを提案します。プロジェクトの詳細はさまざまであり、提案された解決策は絶対的なルールではなくガイドラインとして扱ってください。

react-hook-form の移行については、こちらの react-hook-form 公式ドキュメントをお読みください。PWA プロジェクトには、変更が必要な箇所が 2 つあります。

  1. errors オブジェクトが formState オブジェクトに移動されたので、フォーム errors オブジェクトを、app/components/forms/ のフックの破壊のもう 1 つのレイヤーに移動します。
  1. Controller のレンダープロップを field のプロップに移動します。Render のコールバック署名は、field と fieldState を含むオブジェクトを返します。

React 18 では、ハイドレーション警告は React 17 のような警告ではなくエラーとして表示されます。ハイドレーションエラーが発生した場合、アプリケーションのビルドを妨げるこれらの潜在的なエラーを抑制するには、一部のコードの更新が必要でした。アプリが同形的にレンダリングできるようにするには、これらのエラーの修正が不可欠です。このエラーは、サーバーまたはクライアント間に不一致がある場合に発生します。コンポーネントまたはページが条件付きでレンダリングされる場合は、クライアント固有のコードをレンダリングする前にハイドレーションが完了していることを確認する必要があります。

プロジェクトでハイドレーションが終了したかどうかを判断するユーティリティ関数を作成しましょう。window.__HYDRATING__ で提供される組み込み変数を pwa-kit-react-sdk で使用できます。

プロジェクトで Retail React App テンプレートとは異なる @chakra-ui/react ライブラリのコンポーネントと API を使用している場合は、公式の Chakra 2 移行ドキュメント をご確認ください。

Chakra 2 をサポートするには、Retail React App テンプレートに基づくプロジェクトの更新がいくつかのファイルに必要です。

Chakra 2 では allowMultiple と allowToggle を同時に使用できないため、Accordion コンポーネントの allowToggle を削除します。

Footer コンポーネントでは、@chakra-ui/react から StylesProvider を直接インポートする方法は廃止となっています。代わりに createStylesContext('Footer') を使用して作成する必要があります。

React テストライブラリ v14.0.0 では、すべてのユーザーアクションが非同期であり、ユーザーアクションを実行する前に setup を呼び出す必要があるため、アクションを呼び出す前に userEvent を設定し、userEvent を使用する単体テストでアクションを待ちます。

例:

詳細については、testing-library の userEvent の公式ドキュメントを参照してください。

あるいは、多くの単体テストで setup() を繰り返し呼び出すのを避けるために、テストコンポーネントをレンダリングする直前に app/utils/test-util.js で userEvent を設定し、レンダリング結果とともにそれを返すことで、テストが setup() を呼び出さずにユーザーアクションを実行できるようにします。

Jest-setup には、TextDecoder が jest-setup.js. で定義されていないというエラーをスローする可能性のある疑似依存関係があります。jest-setup.js に以下を追加します。

PWA Kit SDK のバージョン 2.x または npx pwa-kit-create-app@2.x によって生成されたプロジェクトから移行する場合、@salesforce/commerce-sdk-react コードは大幅にリファクタリングされ、app/commerce-api/ ディレクトリが削除されます。API リクエストを処理し、SDK として機能するこれらのファイルの代わりに、@salesforce/commerce-sdk-react がその機能に取って代わります。SDK はこのライブラリを頻繁に使用するため、SDK の v3 リリースは @salesforce/retail-react-app@^1.x の最初のリリースと相関関係があります。

@salesforce/commerce-sdk-react を実装すると、Retail React App 内の多くのファイルが変更されます。変更のサイズを把握するには、この GitHub の差分 で release-2.7.x と release-3.0.x を比較し、@salesforce/commerce-sdk-react を検索してください。差分で、このインポートを含むすべての追加内容をメモします。