next-partial-prefetching-optimizer

部分プリフェッチの最適化

リクエストされた各ソースリンクと遷移先を、それぞれ独立した契約として最適化します。リクエストされたプリフェッチ済み UI、ナビゲーションのみで表示する UI、およびトリガーを、本番環境の instant() テストにします。現在の動作を記録し、最小限の最適化を行い、差分を検証して、合格したテストを回帰テストとして残します。

フレームワークを変更する前に、同梱されているプリフェッチ最適化ガイド node_modules/next/dist/docs/01-app/02-guides/optimizing-prefetching.md を読みます。同梱のガイドを利用できない場合は、オンラインガイドを使用します。プリフェッチの段階、prefetch={true}、セッション固有の UI、コストのトレードオフについては、このガイドを正式な情報源とします。

App Shell に含める内容を変更する場合は、Instant navigation および Caching のドキュメントに従い、キャッシュの配置、Suspense 境界、ローディング UI、認可を扱います。

フレームワークの動作と実装パターンはガイドに従います。このスキルでは、ナビゲーションの契約、本番環境のテスト基盤、信頼できる RED から GREEN へのループ、パリティチェック、差分、レポートを扱います。

これは導入のためのスキルではありません。Cache Components または Partial Prefetching が導入されていない場合は、それぞれの導入スキルを使ってから、このワークフローに戻ります。App Shell 自体が instant() の間にコミットできない場合は、まず next-cache-components-optimizer を使用してから、選択したナビゲーションの作業を再開します。

ワークフローはユーザーの対応を待たずに実行します。リクエストと既存のアプリケーションから契約を判断します。コスト、鮮度、認可、ユーザーに表示される動作を変更せずに安全に推測できず、プロダクト上の判断が本当に妨げになっている場合に限り、ユーザーへの確認を求めて作業を止めます。

ユーザーへの報告

このループはユーザーの対応を待たずに実行するため、実装手順の間で作業を止めないでください。ユーザーが指定したナビゲーションを完了してから、状況を報告します。テスト基盤、ロック、RED/GREEN ループ、ステージ名は内部的な準備要素です。代わりに、ユーザーが実際に目にする動作を報告します。

• ユーザーの言葉で説明します。 検証の仕組みではなく、クリックの前後にユーザーが目にする内容を基準に、ソースリンクと遷移結果を説明します。
• 説明より実演を優先します。 本番環境のブラウザーで実際のリンクを操作し、クリック前に表示されるコンテンツと、クリック後にストリーミングされるコンテンツをユーザーが確認できるようにします。ライブでの実演ができない場合は、変更前後のキャプチャを添付します。
• 技術的な結果の表ではなく、簡潔なクリック手順を示します。 各ナビゲーションについて、ソース URL、クリックするリンク、クリック前に準備できている UI、ナビゲーションを待つ UI、プリフェッチがビューポート内で始まるのか、操作後に始まるのかを1行にまとめます。
• 本当に選択が分かれる場合に限り、質問します。 選択によってコスト、鮮度、認可、表示動作が変わる場合に質問します。ユーザーがすでに PR を依頼している場合や、すべてのナビゲーションを指定している場合は、改めて質問せず、その範囲を完了します。

契約を定義する

ソースルート、対象となる正確なリンクまたはインタラクション、遷移先の Suspense 境界、データの読み取り、既存のプリフェッチポリシー、および既存の instant() テストを調べます。次の内容を記録します。

• クリック前に表示できているべき遷移先の UI
• ナビゲーションまで待つべき再利用可能な UI
• リンク単位のプリフェッチをビューポート内で開始するか、ユーザーの操作後にのみ開始するか

トリガーも契約の一部です。同じ URL へのリンクでも、異なるプリフェッチポリシーを使用する場合があり、その場合は別々のテストが必要です。

トリガーがすでに指定されていない場合は、ガイドのコストモデルを使用します。サーバーを呼び出せるリンクの数を、暗黙のうちに増やしたり、鮮度の契約が不明なデータをキャッシュしたりしないでください。

本番用リグを再利用する

既存の instant-nav.rig.md を読みます。Cache Components の最適化、Partial Prefetching の導入、このオプティマイザーは、同じビルド、認証、データ、 Playwright の契約を共有しています。別のリグを作成するのではなく、正確なソースリンク、 遷移先のマーカー、プリフェッチの予算を追加してください。

プロジェクトにリグがない場合は、rig-template.md を使って リグを見つけ、記録してください。計測する実行は、 experimental.exposeTestingApiInProductionBuild をテスト専用に有効にした本番ビルドまたはプレビューで行う必要があります。 開発環境はルートの診断に役立ちますが、自動リンクプリフェッチは本番環境でのみ行われます。

現在の動作を検証する

正確なソースリンクと遷移先を対象とした既存の instant() テストを検索します。 同じ動作をすでに対象としている場合は、そのテストを拡張してください。そうでなければ、 ガイドの プリフェッチ済みコンテンツと遅延コンテンツのテスト のパターンを使って、クリック駆動のテストを追加してください。

ソースリンク、遷移先、トリガーの契約ごとに、本番ブラウザテストを1つにしてください。 複数の遷移先をループ処理したり、1つのテストでそれらの準備完了結果を収集したりしないでください。 集中的なテストは、1つのブラウザワーカー内で逐次実行できます。

まず、ロックを使わない足場のテストを実行し、リンクが正確なパス名とクエリに遷移すること、 選択した UI がテストユーザー向けに最終的にレンダリングされることを確認します。 この足場のテストをリリースしないでください。

次に、同じインタラクションを instant() 内で実行します。ガイドの肯定的なアサーションと 否定的なアサーションでプリフェッチ結果を捉えつつ、既存の App Shell が表示されたままである 必要があります。ロック解除後は、選択したすべての領域が最終的にレンダリングされる必要があります。

この失敗を RED と判断する前に、 reference/red-test-robustness.md を読んでください。URL が変わる前のタイムアウト、App Shell の欠落、リダイレクト、 データの欠落、古いプレビューは、リグまたはルートの問題を示しています。 プリフェッチを変更する理由にはなりません。

ロック中に望ましい契約全体がすでに満たされる場合は、そこで終了してください。 RED を人為的に発生させるために、prefetch={false} を追加してはいけません。

これらの実行が終わるまでは、テストファイルとテスト API の公開に必要な設定のみ変更できます。 ビルドとテストはフォアグラウンドで実行してください。ハーネスがいずれかをバックグラウンドに 移した場合は、終了するまで待ち、同じタスク内でループを続けてください。テストを書いただけ、 またはビルドが進行中であることは、検証にはなりません。

最小限の最適化を行う

ステージとリンクのポリシーについては、プリフェッチの最適化ガイドに従ってください。契約でキャッシュの配置、Suspense、またはローディング UI の変更も必要な場合は、next-cache-components-optimizer が参照する静的シェルのドキュメントに従ってください。既存の鮮度と認可の動作は維持してください。選択した契約で必要な箇所だけを変更します。

再利用可能な UI をナビゲーションまで待機させる場合は、navigation() のリファレンスに従い、connection() との比較も確認してください。そのうえで、2 つの性質をそれぞれ独立して検証します。instant() のアサーションで確認できるのは、UI がプリフェッチに含まれないことです。基盤となる処理が再利用可能な状態に保たれたことまでは証明できません。再利用可能な処理がステージ境界の下でキャッシュされたままであることを検証してください。

契約で明示的なランタイムステージが必要な場合は、prefetch() と navigation() の API リファレンスに従ってください。

別のナビゲーションに移る前に、受け入れたナビゲーションを 1 つずつ GREEN にしてください。単一のケースをもとに、アプリ全体で使う Link やキャッシュの抽象化を作成しないでください。

最適化によってキャッシュ境界を追加または拡張する場合は、 再検証 に従ってください。書き込み処理によってキャッシュ済みデータが変更される可能性がある場合は、キャッシュへの格納、変更の実行、データの再読み込み、更新後の値の確認というライフサイクル全体をテストしてください。instant() テストに合格して証明できるのは、プリフェッチによって即座に表示できることです。変更後の鮮度ではありません。

検証してリリースする

実際のソースリンクを対象とした、合格済みのロック済みテストは回帰テストとして残してください。読み込み後のページのコンテンツ、順序、空状態とエラー状態、認可、鮮度、リダイレクト、直接読み込み時の動作を維持してください。

最後に、最適化だけを削除してテストを再実行します。

• App Shell は GREEN のままです。
• 選択したプリフェッチ契約は RED に戻ります。

最適化を再適用し、再び GREEN になることを確認します。この差分テストにより、テストが無関係なキャッシュ状態ではなく、対象のリンクポリシーそのものを検証していることを証明できます。リリースするのは、最終的な肯定テストだけにしてください。

上記のユーザー向けフォーマットを使って、検証済みの結果を報告してください。プリフェッチはベストエフォートであり、完了していない場合は App Shell がフォールバックとして機能することを正確に伝えてください。

リクエスト数、転送バイト数、キャッシュの動作は測定値として扱い、instant() の契約の一部には含めないでください。プライベートな RSC URL や、next-router-prefetch などの内部ヘッダーを使ってリクエストを分類しないでください。公開テスト API で検証できるのはレンダリング結果であり、各リクエストを生成したプロトコルステージではありません。

完了チェックリスト

• Cache Components と Partial Prefetching がすでに導入されています。
• 対象 UI、トリガー、鮮度、認可の制約について、依頼と既存のアプリケーションに基づいて確認済みです。
• テストでは正確なソースリンクをクリックし、正確な遷移先を検証します。
• ソースリンク、遷移先、トリガーの各契約に、それぞれ専用のテストがあります。
• ロック解除状態のベースラインとロック済みの RED で、同じ本番用アーティファクトを使用しました。
• RED／GREEN の反復中、App Shell は表示されたままでした。
• ロック中、選択した UI は表示され、ナビゲーション時のみ表示する UI は表示されません。
• 再利用可能な、ナビゲーション時のみ必要な処理は、そのナビゲーションステージの下でキャッシュされたままです。
• 新たにキャッシュしたデータを更新できる場合は、そのデータをキャッシュに格納した後、変更テストで次の読み込み時に期待するデータが返されることを確認します。
• 読み込み後のコンテンツ、鮮度、認可、直接アクセス時の動作は変更されていません。
• 最適化だけを削除すると、契約は RED に戻ります。
• 最終的な肯定 instant() 回帰テストをリリースします。

引き継ぎ

リクエストで指定されたナビゲーションをすべて完了してください。Cache Components または Partial Prefetching を採用しない場合は、next-cache-components-adoption または next-partial-prefetching-adoption を使用してから、このワークフローに戻ってください。App Shell が instant() のもとでコミットできない場合は、next-cache-components-optimizer を使用し、その後、選択したナビゲーションを再開してください。ビルドやテストをユーザーが監視しなければならない状態のままにしないでください。

追加の最適化候補は、対象範囲にすでに含まれている場合を除き、変更せずに報告してください。選択したリンクごとのポリシーを、アプリ全体に適用する Link やキャッシュの抽象化に拡大しないでください。

ファイル

• rig-template.md：既存の instant-nav.rig.md がないプロジェクト向けの、本番ビルド、テストコンテキスト、ナビゲーションの契約、および無人ループの検出。
• reference/red-test-robustness.md：信頼性の高い RED および差分チェック。

関連資料

• プリフェッチの最適化
• 即時ナビゲーション
• キャッシュ
• プリフェッチ