v3 へのアップグレード

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

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

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

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

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

⚛️ React 18、Node 16 / 18、Chakra 2 などのサポートを含む、主要なベンダーライブラリのアップデート。

v2.7.x から v3.x に移行するときに最初に決定する必要があることの 1 つは、テンプレートの拡張性を活用するかどうかです。この利点を活用するには、@salesforcef/retail-react-app (または別の拡張可能なアプリ) から少なくとも 1 つのファイルをインポートする必要があります。ベーステンプレートから継承するファイルの数を選択できますが、少なくとも 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 から削除されました。

v3.0.0 以降、PWA Kit は異なるフェッチ戦略である withReactQuery を使用します。この戦略は、react-query ライブラリを活用し、SSR レンダリングパスでのクエリを有効にします。@salesforce/retail-react-app は、react-query によって動く @salesforce/commerce-sdk-react を使用します。

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

v3 にアップグレードしようとしており、かつ引き続き getProps を使用しようとしているプロジェクトの場合は、AppConfig コンポーネントを withLegacyGetProps コンポーネントでラップします。

package.json の依存関係を次のように変更します。

package.json のエンジンを更新し、Node ^16.11 と npm ^9 をサポートします。バージョン 2 が Chakra の最新メジャーバージョンであるため、package.json の peerDependencies から @chakra-ui/system を削除します。

jest-environment-jsdom の依存関係であるバグ nswapi があり、Chakra 2 とは互換性がありません。Modal コンポーネントを使用する一部のテストでは、エラー ':disabled):not([disabled]' is not a valid selector がスローされます。このバグは単体のテストにのみ影響し、ブラウザの実行には影響しません。npm 8 を使用し、nwsapi パッケージの 2.2.2 バージョンを強制する上書きを追加します。また、npm 7 のサポートは削除されます。

overrides プロパティを package.json に追加して、パッケージのバージョンを適用します。

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

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

1. errors のオブジェクトが formState のオブジェクトに移動されたため、フォーム errors のオブジェクトを app/components/forms/* のフックのもう 1 つの破壊レイヤーに移動します。

2. Controller のレンダリングプロップを field のプロップに移動します。Render のコールバック署名は、field と fieldState を含むオブジェクトを返します。

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

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

条件付きレンダリングを使用する場所にこの関数を追加します。PWA Kit プロジェクトには、この関数を追加する場所がいくつかあります。

こちらを参照してください。

DOM レンダリングを妨げるブラウザーのプラグインがインストールされている場合、フッターでハイドレーションエラーが発生する可能性があります。たとえば、LastPass 拡張機能を使用している場合、LastPass がブラウザーのレンダリングを引き継いでアイコンを挿入し、フィールド内ポップアップを有効にするため、フッターの Subscribe コンポーネントでエラーが表示されます。この引き継ぎがハイドレーションプロセス中に発生すると、エラーが表示されます。isHydrated() を使用せずに活用できる簡単なトリックの 1 つは、次のように入力コンポーネントの順序を切り替えることです。

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 diff の release-2.7.x → release-3.0.x を比較し、@salesforce/commerce-sdk-react を検索してください。diff では、このインポートを追加するすべての追加内容を確認してください。