Communitygithub.com

Next.js キャッシュコンポーネント最適化

`cacheComponents: true` が設定されたNext.jsアプリケーションを最適化します。初回描画時の静的シェル、またはルート間のアプリ内ナビゲーションのいずれかを対象に、適切な診断ループを選択して実行します。

Next.js キャッシュコンポーネント最適化 とは?

このスキルは、Next.jsアプリケーションにおいて `cacheComponents: true` 設定下でのレンダリングパフォーマンスを向上させるための専門ツールです。「ページレンダリングループ」と「ナビゲーションループ」の2つの診断ループを提供し、問題に応じて適切なループを選択・実行します。 ページレンダリングループは、単一ページの静的シェルを拡大し、Suspenseのフォールバック領域を最適化します。一方、ナビゲーションループは、ユーザーがリンクをクリックしてルートAからBへ移動する際に、Bのデータが解決されるのを待たずにBの静的レイアウトを即座に表示するための最適化を行います。 スキルは自動ブラウザ操作(`agent-browser` CLI)と開発MCPサーバー(`mcp get_logs`)を活用し、Cookieによる動的データ書き込みの凍結、ベースラインスクリーンショットの取得、そして実際の視覚的な差分に基づく検証を行います。リファクタリングには「プッシュダウン」(I/OをSuspenseでラップした子コンポーネントに抽出)と「キャッシュ」(`'use cache'` + `cacheLife`)の2つの主要なレバーを提供し、すべての変更は計画モードを通じて提案されます。 このスキルは、`next-dev-loop` と連携して動作し、`cacheComponents: true` が設定されていない場合は拒否します。また、ルートが完全にブロッキング状態(HTTP 500や `blocking-route` ログなど)の場合は早期に停止し、ユーザーに動的アクセスを `<Suspense>` でラップするよう促します。

対応~Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add https://github.com/0n6k4v-Coder/skills/tree/HEAD/next.js/next-cache-components-optimizer

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

next-cache-components-optimizer

2つのループ、共有のレバーとプリミティブ、異なる診断:

  • ページレンダリングループ (ppr-loop.md) — 単一ページの静的シェルを拡大します。シェルのみのレンダリングでSuspenseのフォールバック領域をランク付けします。
  • ナビゲーションループ (instant-nav-loop.md) — ユーザーがリンクAからBへクリックしたとき、Bのデータが解決されるのを待たずにBの静的レイアウト(クローム、構造、コンテンツ形状のフォールバック)を即座に表示します。pushstate 後にBのサスペンドされた境界をキャプチャし、各々を suspended_by[].name で分類し、SSR専用のクライアントフックを削除します。

一つを選択し、エンドツーエンドで実行します。

必要条件

  • このセッションで next-dev-loop が開始されていること — これによりヘッドレスブラウザが開き、agent-browser CLIが公開され、mcp get_logs を提供する開発MCPサーバーが配線されます。
  • next.config.ts で cacheComponents: true が設定されていること。そうでない場合は拒否します。

事前チェック(共有)

  1. cacheComponents: true を確認します。
  2. (next-dev-loop からの)ヘッドレスブラウザで、各ループが必要とするページにユーザーが既にいること — ログイン済みで、任意の状態がセットアップされていること。このスキルは認証、SSO、MFAを駆動できません。手動セットアップを開始点とします。(各サブループは、どのページを期待するかを指定します。)
  3. agent-browser get url で現在のルートを固定します。

各ループは、必要に応じてインスタントCookieを設定します(下記の共有 instant cookie セクションを参照)。

インスタントCookie(共有)

両方のループは next-instant-navigation-testing Cookieを使用して、フレームワークの動的データ書き込みを凍結します。設定されると、ページ上の可視コンテンツは静的シェル + Suspenseフォールバックになります — これをキャプチャして最適化を評価します。

保留ロックタプル [0, "<ユニークID>"] で設定します。IDは任意のユニークな文字列です。慣例として、競合するスコープが衝突しないように p で始まるランダムスタンプを使用します:

agent-browser cookies set next-instant-navigation-testing '[0,"p<random>"]' \
  --url <origin>

各ループの事前チェックは、フロー内でいつ設定するかを指定します。最後にクリアします(下記の teardown を参照)。

ループの決定

  • ページレンダリング — 1つのルートの初期読み込みに関する問題の場合。ppr-loop.md を読んでください。
  • ナビゲーション — 2つのルート間のナビゲーションに関する問題の場合。instant-nav-loop.md を読んでください。

曖昧な場合 → ユーザーに尋ねてください。

共有リファクタリングレバー

  • プッシュダウン — I/OをSuspenseでラップされた子コンポーネントに抽出し、親を静的に保ち、静的な兄弟をシェルに引き上げます。
    • 再帰的に行い、盲目的にラップしないでください。 Suspense境界がすでに静的コンテンツとI/Oの両方を含むコンポーネントをラップしている場合、内部を読み取り、I/O依存のJSXを新しいリーフに抽出し、静的な兄弟を引き上げます。
  • キャッシュ — 'use cache' + cacheLife(<プロファイル>)。常にユーザーに鮮度を尋ね、プリセット(seconds / minutes / hours / days / weeks / max / default)にマッピングします。

プッシュダウンとキャッシュは組み合わせ可能です: プッシュダウンは静的な構造を引き上げ、キャッシュは残りのデータギャップを排除します。

計画モードでの提案(共有)

各リファクタリングは、適用前に計画モードを経由します。これをシグナルとして扱ってください: 適用作業は、テンプレート化された編集ではなく、重要なエージェントエンジニアリングです。このスキルはフレームワークを提供します — どのレバーを使うか、どの候補を修正するか、期待される可視デルタは何か — しかし実際の作業(どのファイルを編集するか、I/Oをクリーンに抽出する方法、新しいSuspense境界をどこに配置するか、どの cacheLife プロファイルをユーザーに尋ねるか)は、あなたが熟考して判断する必要があります。計画モードは、コードに触れる前に首尾一貫した提案を強制し、ユーザーにそれらの決定のいずれかを変更する機会を与えます。

シェルなしの早期終了(共有)

レバーは、拡大またはキャッシュするシェルが存在することを前提としています。ルートが完全にブロッキングされている場合 — mcp get_logs で blocking-route または NEXT_STATIC_GEN_BAILOUT のHTTP 500、または可視的にレンダリングされたページでSuspense境界がゼロの場合 — シェルはありません。構造的なブロッカーを表面化して停止します。ユーザーは、問題のある動的アクセスを <Suspense> でラップしてからでないと、どちらのループも役に立ちません。

検証には可視デルタが必要(共有)

各ループは、変更を適用する前にシェルのベースラインスクリーンショットをキャプチャし、その後再スクリーンショットを撮ります。最終サマリーで両方のパスを報告し、ユーザーが何が変更されたかを確認できるようにします。2つのキャプチャは明らかに異なっていなければなりません — フォールバック領域が縮小された、コンテンツが静的サーフェスに昇格した、ターゲットのフォールバックが消失した、またはコンテンツ形状になった。同一に見えるキャプチャは、リファクタリングが機能しなかったことを意味します。元に戻してください。「クリーンにコンパイルされる」は基準ではありません。

各スクリーンショットの前に開発オーバーレイを非表示にします。 Next.jsの開発オーバーレイ(ドキュメントルートの <nextjs-portal>)は、インスタントナビゲーションガイダンス、ビルドエラー、および他の開発用クロームをレンダリングし、Before/Afterの比較を汚染します。非表示にし、スクリーンショットを撮り、復元します:

agent-browser eval "document.querySelector('nextjs-portal').style.display='none'"
agent-browser screenshot <path>
agent-browser eval "document.querySelector('nextjs-portal').style.display=''"

アンチパターン(共有)

詳細なSuspense境界をトップレベルのローディングスケルトンに置き換えないでください。 セグメント全体に対する loading.tsx、またはルートレベルの <Suspense fallback={<Skeleton />}>(さらに悪いことに、UIを空白にする fallback={null})は、このスキルの最適化を無効にします — 各詳細な境界の上に実際の静的クロームを抽出し、領域ごとにコンテンツ形状のフォールバックを使用することです。粗い「ページ読み込み中」の代用品は、作業を完全にバイパスします。

注意点(共有)

  • 開発環境は本番環境のようにプリフェッチせず、ルートは初回ヒット時にコンパイルされます。そのため、ナビゲーションまたはリロード後、DOMは最終的な本番エクスペリエンスよりも著しく長く更新され続けます。Reactツリーをキャプチャしたりスクリーンショットを撮ったりする前に、DOMが安定するのを辛抱強く待ってください — 例えば、document.documentElement.innerHTML.length を2回連続して読み取り、変更がなくなるまでポーリングします。固定の短い遅延では、レンダリング途中のサンプリングリスクがあります。
  • 開発ネットワークトラフィックを調べることでナビゲーションプリフェッチを検証しようとしないでください — 開発環境はプリフェッチ要求をまったく発行しません。そのため、ネットワークタブ、手動の router.prefetch() 呼び出し、<Link prefetch={true}> は、コードが正しいかどうかに関係なくすべて壊れているように見えます。instant-nav-loop.md の verify にあるCookieロックされたSPAナビゲーションレシピは、これに対する正規のレシピです — プリフェッチが実際に発火することを要求せずに、本番環境がプリフェッチされたRSCにプリレンダリングするものをシミュレートします。それを使用してください。ネットワークタブの代替を発明しないでください。
  • 診断パイプラインは不安定になる可能性があります — DevToolsのアタッチメントタイミング、DOMセトルの競合、開発コンパイルの影響により、実行ごとに一貫性のないキャプチャが生成されることがあります。結果がおかしいと感じた場合(予期しない候補が現れた、または期待した候補が現れない場合)、診断を2〜3回再実行してクロスチェックしてください。一貫して現れる境界は本物で、1回限りの出現はノイズです。

リファレンス(共有プリミティブ)

agent-browser react suspense          add --only-dynamic to filter
--json                                server-side to actually-
                                      suspended boundaries. Each
                                      entry has jsx_source +
                                      suspended_by[] with raw blocker
                                      names (usePathname, cookies,
                                      fetch, cache, ...); classify by
                                      name for per-loop rules

POST /__nextjs_original-stack-frames  body { frames: StackFrame[],
                                      isServer, isEdgeServer,
                                      isAppDirectory }; returns one
                                      result per frame with
                                      file:line:column

mcp get_logs                          dev MCP tool from
                                      next-dev-loop; surfaces
                                      blocking-route /
                                      NEXT_STATIC_GEN_BAILOUT 500s

cacheLife('<profile>')                default | seconds | minutes
                                      | hours | days | weeks | max

ループごとのプリミティブは instant-nav-loop.md にあります。

後片付け(共有)

名前でCookieを削除します — 期限切れスタンプで上書きします:

agent-browser cookies set next-instant-navigation-testing x \
  --url <origin> --expires 1

agent-browser cookies clear(引数なし)は決して使用しないでください — 認証を消去します。


next-dev-loop の兄弟 — 最初にそれを開始してください。

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

0n6k4v-Coder/skills

Translates Figma motion and animations into production-ready application code. Use when implementing animation/motion from a Figma design — user mentions "implement this motion", "add animation from Figma", "animate this component", provides a Figma URL whose node is animated, or when `get_design_context` returns motion data or instructs you to call `get_motion_context`.

0n6k4v-Coder/skills

Motion / animation context for the `use_figma` MCP tool — animating Figma nodes via manual keyframes, animation styles, easing, and timeline duration. Load alongside figma-use whenever a task involves adding, editing, or inspecting animation on a node.

0n6k4v-Coder/skills

Generate motion specification annotations from After Effects timeline data. Use when the user mentions "motion", "motion spec", "animation spec", "timeline", or wants to document a component's animation properties.

0n6k4v-Coder/skills

Turn on Cache Components in a Next.js app and resolve the blocking routes it surfaces. Use when the user wants to enable, adopt, or migrate to Cache Components, flip the `cacheComponents` flag, work through a flood of blocking-prerender / instant validation errors, run the `cache-components-instant-false` codemod, or decide between opting routes out with `export const instant = false` and fixing them in place.

0n6k4v-Coder/skills

Verify Next.js runtime behavior after editing app code. Use this skill to confirm a change actually works in a running app — not just that it compiles or type-checks. Combines /_next/mcp (Next.js's view) with agent-browser (the browser's view). Requires a running `next dev`.

関連スキル