next-cache-components-adoption
アプリで Cache Components を有効にし、ビルドが成功するまで導きます。このスキルは作業の順序を決めます。エラーごとのレシピは dev オーバーレイの修正カードとビルドのターミナル出力にあります。Cache Components への移行ガイド は、このスキルが適用する概念と API ごとのレシピに関する正規のリファレンスです。スキルの手順がパターン("use cache"、cacheLife、<Suspense> の配置など)を参照する場合は、詳細な説明が必要なときにこのガイドを参照してください。
必要条件
-
App Router プロジェクト。 Cache Components は App Router の機能です。
pages/ルートではcacheComponents: trueは何も行いません。プロジェクトにpages/またはsrc/pages/ツリーがあるがapp/またはsrc/app/ツリーがない場合は、処理を停止してユーザーに伝えてください。Pages → App の移行はそれ自体が独立したプロジェクトであり、このスキルの対象外です。ハイブリッドアプリ(pages/とapp/の両方がある)は問題ありません。フラグはapp/ルートにのみ影響し、pages/ルートは影響を受けず、オプトアウトも必要ありません。 -
Next.js 16.3 以降。 このリリースで、このスキルが依存する機能(トップレベルの
cacheComponents、export const instant、dev オーバーレイのインスタントナビゲーション検証警告、cache-components-instant-falsecodemod)が導入されます。next --versionが 16.3 未満を報告する場合は、最初にアップグレードしてください。npx @next/codemod@latest upgrade latestを実行して、バージョン間の codemod を適用します。- 該当するバージョンアップグレードガイド(例:バージョン 16)を読み、codemod がカバーしない内容を確認します。
-
互換性のない設定キーがないこと。
cacheComponents: trueは、dynamic、revalidate、またはfetchCacheをエクスポートしているファイルがあるとエラーになります。削除するのではなく、変換してください。 各エクスポートはルートが引き続き必要とする動作をエンコードしています。移行ガイドのキーごとのセクションを参照して、それぞれを Cache Components の同等のものに移行してください。値がまだクリーンに変換できない場合は、// TODO: Cache Components adoption — restore revalidate = 3600のようなコメントを残して、後続のループで対応できるようにします。cache-components-instant-falsecodemod はこれらには触れません。 -
experimental.dynamicIOは致命的です。 これはトップレベルのcacheComponentsに名前が変更されました。古いキーはビルドが実行される前に中止されます。最初に削除するか、cacheComponents: trueに置き換えてください。experimental.useCacheは依然として非推奨のエイリアスとして受け入れられますが、cacheComponents: trueが設定されると冗長になるため、明確さのために削除してください。
注意事項
-
フラグ設定前の合格ベースラインはありません。 アプリがすでに
"use cache"を使用している場合、フラグ設定前のビルドはplease enable the feature flag cacheComponentsエラーになります。フラグを有効にすることが最初に行うことです(インクリメンタルでは codemod の前、ダイレクトではルート修正の前)。合格ビルドを取得した後に行うことではありません。開始時のサマリーにこれを記載し、回帰と誤解されないようにしてください。 -
オフラインドキュメント。 ガイドリンクのオフラインコピーは
node_modules/next/dist/docs/にあり、ディレクトリレイアウトは順序付けのために番号が付けられています(例:node_modules/next/dist/docs/01-app/02-guides/migrating-to-cache-components.md)。末尾のファイル名はスラッグと一致します。番号付きのプレフィックスを予測できない場合は、find node_modules/next/dist/docs -name '<slug>.md'で解決できます。/docs/messages/*エラーページはバンドルされていません。オフラインドキュメントが完全に欠落している場合は、npx @next/codemod@latest agents-mdを実行して、バージョンに一致するインデックスをAGENTS.md/CLAUDE.mdに書き込みます。
作業の形
ループは1つです。ルートツリーをトップダウンで、一度に1つの機能ずつ進め、next dev とブラウザを使用して各ルートを採用します。ビルドは各機能の最終確認であり、作業面ではありません。
ステップ1での選択は、最初に検証エラーをすべて沈黙させるか、進みながら修正するかです。どちらの場合でもループは同じです。
- 静かな事前ステップあり(インクリメンタル)。 codemod を実行して、すべてのページとレイアウトを検証からオプトアウトします。codemod で修正できないもの(同期 I/O 呼び出し、残っている
revalidate/dynamic/fetchCacheエクスポート)も修正すると、ビルドは成功します。これを独自の PR として出荷し、その後ループを開始します。1つずつオプトアウトを削除し、そのルートを採用します。作業を小さなレビュー可能な PR に分割します。 - 事前ステップなし(ダイレクト)。
cacheComponentsを有効にし、ビルドが最初にフラグを立てたルートからループを開始します。同じループですが、すべての修正は採用が完了するまで1つのブランチに置かれます。
どちらの場合も、ルートごとの成功基準は同じです。dev ループでエラーが報告されず、next build が成功すること。 各機能の後でユーザーに確認してください。ほとんどの時間は事前ステップではなくループ内で費やされることを想定してください。
背景
cacheComponents: true は、すべてのルートがプリレンダリング可能であることを要求します。リクエスト時のデータを <Suspense> の外部で読み取るルートは「ブロッキング」であり、ビルドに失敗します。export const instant = false は、ルートがブロックを許可されているとマークし、dev とビルドの両方でクリアします。レイアウトで使用すると、その下のサブツリー全体をカバーします。"use cache" 関数でラップされた読み取りは、キャッシュ境界としてカウントされ、ブロッキング読み取りではありません。
エージェントに対して、次の3つのクラスのブロッカーがこの順序で問題を引き起こします。
- リクエスト時の読み取り(
cookies()、headers()、await params、await searchParams)。これら4つはすべて、ページまたはレイアウトの先頭で await されるとブロックします。paramsとsearchParamsは、cookies や headers のように「リクエストデータ」として認識されないため、見落とされがちです。修正方法は、読み取りを<Suspense>でラップされた子コンポーネントにプッシュすることです。params/searchParamsの場合は、Promise を子コンポーネントに転送してそこで await します。ページの先頭で await しないでください。 - モジュール/レンダリング時の同期 I/O(
new Date()、Date.now()、Math.random()、crypto.randomUUID())。これらはinstant = falseでもビルドに失敗します。オプトアウトでは抑制されません。これらが共有レイアウトにある場合、その下のすべてのルートをブロックします。codemod では修正できません。それぞれを変換する必要があります(安定している場合は"use cache"でキャッシュするか、リクエストごとの場合はawait connection()+<Suspense>でラップします)。他の処理を実行する前に、リポジトリ全体でこれらの呼び出しを grep してください。 - リクエストデータを読み取る
"use cache"ファイル。 トップレベルの"use cache"ディレクティブがあるファイルはinstantをエクスポートできません。この2つを組み合わせるとOnly async functions are allowed to be exported in a "use cache" file.エラーが発生し、そのルートに対してディレクティブが間違っていたことを意味します。codemod を実行する前に削除してください。
作業面
ブロッキングルートの検出
作業中は next build よりも next dev を優先して使用してください。
next dev— 作業面。ルートにアクセスすると、そのブロッキングエラーが dev オーバーレイに完全なスタックトレースとエラーごとのドキュメントへの修正カードリンクと共に表示されます。一度に1つのルートを処理します。エラーが1か所に蓄積されることはありません。ルート自体はまだ HTTP 200 を返すため、オーバーレイ(または.next-dev.log)を読み、ステータスコードは無視してください。オーバーレイがクリアされたことは、ルートクリーンの半分です。残りの半分はブラウザによる検証(ステップ2を参照)と、そのルートのビルド成功です。next build— 検出のみ。ビルドはnext devの信頼できるチェックであり、代わりになるものではありません。ループ内の各機能の最後のゲート(ルートごとの成功基準の一部としてのビルド成功)として、またアプリ全体の最終検証として使用してください。インクリメンタルでは、ビルドは事前ステップ(codemod ですべてのルートをオプトアウトし、共有レイアウトに同期 I/O ブロッカーがないこと)も確認し、その PR を出荷する前に確認します。ルートの作業中に dev ループの代わりにビルドに手を伸ばさないでください。クリーンなコンパイルエラーは、何が静的シェルに含まれ、何がストリーミングされたかを教えてくれません。デフォルトではビルドは最初のブロッキングルートで停止するため、作業の規模を把握するのにも適していません。反復処理時に役立つ2つのフラグがあります。--debug-build-pathsは、指定したルートのみをビルドします(プロジェクトルートからの相対ファイルパスのカンマ区切りグロブパターン。例:--debug-build-paths="app/admin/**/page.tsx"— URL パスではありません。--debug-build-paths="app/(marketing)/about/page.tsx"—/aboutではありません。--debug-build-paths="app/admin"は何もマッチせず、静かにゼロルートをビルドします)。--debug-prerenderは早期終了を無効にし、ビルドが最初のプリレンダリング失敗後も続行し、すべてのブロッキングルートを報告し、発信元のファイルと行を示すより完全なスタックトレースを出力します。
すべてのブロッキングエラーにはドキュメントページがあります。それを開いてください。dev オーバーレイとビルドターミナルの両方に、各エラーとともに https://nextjs.org/docs/messages/<slug> リンクが表示されます。そのページが修正の正規のレシピです。インラインメッセージは要約です。パターンを知っていると思っていても、遭遇するすべての異なるエラーに対してリンクをフェッチしてください。レシピは進化し、同じエラークラスでもルートが読み取る内容によって正しい修正が異なる場合があります。インラインメッセージだけでアドリブしないでください。(/docs/messages/* ページはオフラインではバンドルされていません。ネットワークがない場合は、node_modules/next/dist/docs/ の下にある API ごとのガイドにフォールバックし、報告するときにその制限を注意してください。)
各修正のランタイム検証
ビルドが成功したり、オーバーレイがクリアされたりしただけでは、ルートが実際に正しく動作することの証明にはなりません。Cache Components はランタイムに関する問題(ストリーミングデータを持つ静的シェル)です。最後だけでなく、各修正の後に検証してください。
優先順位:
-
next-dev-loop— 強く推奨。/_next/mcpをagent-browserを介してライブブラウザとクロスチェックし、コンパイル時とランタイムの両方の問題を1回のパスで明らかにします。診断(React ツリー、サスペンス境界、コンソール + ネットワーク)は、手動でnext devを調べるよりも豊富です。ループを開始する前にインストールしてください。
next devだけでは説明できない何かに遭遇するまで待たないでください。次のコマンドを実行します。npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loopこのスキルは
agent-browser >= 0.27.0を必要とし、その設定を案内します。Turbopack が必要です。
package.jsonのdevスクリプトが--webpackを渡している場合は、ユーザーにその旨を伝え、webpack に留まる理由があるかどうかを尋ねてください。理由がなければ、Turbopack(Next.js 16.3+ のデフォルト)に切り替えてください。webpack を維持する場合は、このインストールをスキップし、代わりにビルド専用ループを使用してください。next-dev-loop自体をインストールするために許可は必要ありません。これは dev 依存関係をインストールするようなツールです。ユーザーがオンラインの場合は、検証のためにインストールすることを簡単に伝えてください。非対話型実行(CI、ダッシュボード、サンドボックス)では、尋ねずにインストールしてください。「ユーザーにプロンプトを表示できない」ことはスキップする理由にはなりません。スキップする正当な理由は、実際の技術的ブロッカー(ネットワークなし、npm なし、読み取り専用ファイルシステム、新しい依存関係禁止ポリシー、webpack のみの dev スクリプト)のみです。スキップする場合は、最終報告書で具体的なブロッカーを明記してください。 -
自分で操作できるブラウザ。 Playwright、
agent-browserを直接、任意のブラウザ自動化ツール。next-dev-loopが本当にブロックされている場合にのみ使用してください。フレームワーク側のチェック(/_next/mcp)を見逃すため、DOM アサーションだけではすべての回帰をキャッチできるわけではありません。「検証済み」と呼ぶものについてはより慎重になってください。 -
ビルドのみ。 dev サーバーをまったく実行できない場合、ビルドが唯一のシグナルです。
<Suspense>のない○ (Static)ルートはビルドによって完全に検証されます(テストするストリーミングはありません)。◐ (Partial Prerender)ルートはシェルのみ検証されます。報告時にその旨をフラグしてください。 -
ツールがまったくない。 ユーザーに dev サーバー(またはビルド)を実行して、表示された内容を報告するよう依頼するか、到達したマイルストーンをコミットして引き継いでください。
ステップ 1: 戦略を選択する
ユーザーに確認してください。PR の形状に関する質問として組み立て、規模の判断を求めないでください。ユーザーと話すときは、内部ラベル(インクリメンタル、ダイレクト、マイルストーン A)を決して使用しないでください。それらはあなた自身の枠組みです。PR と機能の観点から質問してください。例:「最初に Cache Components をオンにしてすべてのルートを検証からオプトアウトする PR を作成し、実際のルート採用を機能ごとに後続の PR で処理しますか?それともすべてを1つのブランチで行いますか?」 小さなアプリでも、インクリメンタルパスには価値があります(レビュー可能なサイズの PR、元に戻せる、// TODO: Cache Components adoption マーカーは次のセッションの作業キューとしても機能します)。代わりに選択しないでください。
確認するユーザーがいない場合は、デフォルトでインクリメンタルを選択し、その選択を文書化してください。
- インクリメンタル — 静かな事前ステップ + ループ。codemod を実行してすべてのページとレイアウトを検証からオプトアウトし、ビルドを成功させ、停止してユーザーに確認し(事前ステップの終了を参照)、その後ステップ 2 のループに入り、各機能を後続の PR として出荷します。
- ダイレクト — 事前ステップをスキップ。
cacheComponentsを有効にして、すぐにステップ 2 のループに進みます。ビルドのブロッキングルートが作業キューになります。
インクリメンタル
codemod を呼び出す前に、codemod で修正できない2つのクラスのブロッカーを修正してください。
-
モジュール/レンダリング時の同期 I/O。 リポジトリ全体で
new Date()、Date.now()、Math.random()、crypto.randomUUID()を grep してください(app/**/layout.{js,jsx,ts,tsx}だけでなく、読み取りはレイアウトによってインポートされる任意のコンポーネントに存在する可能性があります)。それぞれの一致を、blocking-prerender-*エラーカードのレシピを使用して変換してください。 -
互換性のないセグメント設定。
app/全体で^export const (revalidate|dynamic|fetchCache)を grep し、上記の「必要条件」の注意事項に従って変換してください。codemod はこれらに触れません。そのままにしておくと、codemod の後にビルドが失敗します。
codemod はダーティなワーキングツリーでは実行を拒否します。まず無関係な作業をコミットするかスタッシュするか、--force を渡して WIP と一緒に編集をランディングできるようにします。よくある誤検出:Next.js を最近アップグレードした場合、package.json とロックファイルはすでにダーティになっている可能性があります。まずそれらをコミットしてください。
@canary チャネルの codemod を使用してください。