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 から削除されました。
テンプレートの拡張性を利用するためにプロジェクトを移行する場合、PWA Kit SDK のバージョン 2.x と npx pwa-kit-create-app@2.x
によって生成されたプロジェクトは @salesforce/commerce-sdk-react
に依存していないのに対し、新しいコード @salesforce/retail-react-app@^1.x
はこのライブラリを頻繁に使用し、多くのファイルに触れて変更することに注意してください。変更の規模を把握するには、この Github diff 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
でラップする必要があります。
v3
にアップグレードしようとしており、かつ引き続き getProps
を使用しようとしているプロジェクトの場合は、AppConfig コンポーネントを withLegacyGetProps
コンポーネントでラップします。
withReactQuery
と 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 つの変更が必要な箇所があります。
-
errors
のオブジェクトがformState
のオブジェクトに移動されたため、フォームerrors
のオブジェクトをapp/components/forms/*
のフックのもう 1 つの破壊レイヤーに移動します。 -
Controller
のレンダリングプロップをfield
のプロップに移動します。Render
のコールバック署名は、field
とfieldState
を含むオブジェクトを返します。
React 18 では、ハイドレーション警告は React 17 のような警告ではなくエラーとして表示されます。ハイドレーションエラーが発生した場合、アプリケーションのビルドを妨げるこれらの潜在的なエラーを抑制するには、一部のコードの更新が必要でした。アプリが同形的にレンダリングできるようにするには、これらのエラーの修正が不可欠です。このエラーは、サーバーまたはクライアント間に不一致がある場合に発生します。コンポーネントまたはページが条件付きでレンダリングされる場合は、クライアント固有のコードをレンダリングする前にハイドレーションが完了していることを確認する必要があります。
プロジェクトでハイドレーションが終了したかどうかを判断するユーティリティ関数を作成しましょう。window.__HYDRATING__
で提供される組み込み変数を pwa-kit-react-sdk
で使用できます。
条件付きレンダリングを使用する場所にこの関数を追加します。PWA Kit プロジェクトには、この関数を追加する場所がいくつかあります。
こちらを参照してください。
DOM レンダリングを妨げるブラウザーのプラグインがインストールされている場合、フッターでハイドレーションエラーが発生する可能性があります。たとえば、LastPass 拡張機能を使用している場合、LastPass がブラウザーのレンダリングを引き継いでアイコンを挿入し、フィールド内ポップアップを有効にするため、フッターの Subscribe
コンポーネントでエラーが表示されます。この引き継ぎがハイドレーションプロセス中に発生すると、エラーが表示されます。isHydrated()
を使用せずに活用できる簡単なトリックの 1 つは、次のように入力コンポーネントの順序を切り替えることです。
プロジェクトで 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 diff の release-2.7.x
→ release-3.0.x
を比較し、@salesforce/commerce-sdk-react
を検索してください。diff では、このインポートを追加するすべての追加内容を確認してください。