nextjs-ppr-patterns

Next.js 16 の部分的プリレンダリングパターン

Cache Components モデルにおける Next.js 16 App Router の部分的プリレンダリング（PPR）について、PPR によって必要となる判断と、その決め方を説明します。エージェントがコードの作成やレビュー時に適用できるようにまとめています。6 カテゴリにわたる 21 のルールを、簡単なものから複雑なものの順に掲載しています。PPR の有効化 → 静的／動的境界の理解 → キャッシュ → 実行時データの処理 → ページ全体の組み立て → フォームとウィザードの構築、の順です。各ルールは、Next.js 14/15 を前提とするモデルが誤って選びがちな判断を具体的に正します。モデルがすでに正しく対応できる内容についてのルールはありません。

バージョン固有です。 このスキルは Next.js 16 を対象としています（cacheComponents による PPR、React 19.2）。Next.js 14/15 の experimental.ppr フラグと export const experimental_ppr ルートエクスポートは削除されました。詳しくは setup-enable-cache-components を参照してください。既存のアプリを移行する場合は、移行ガイドを参照してください。

作成してから検証します。 これらのルールは PPR の作成を支援するものであり、実際に何がレンダリングされたかを判断することはできません。境界を実証的に分析するには、静的シェルとハイドレーション後の DOM を比較して動的な穴を特定し、'use client' のアイランドを見つけ、読み込みを測定し、ルートが動的である理由を説明します。そのために、_debug-boundaries.md に従って next build と実際のブラウザーを使用します。

適用する場面

• 静的なクロームと、パーソナライズされたコンテンツ、リアルタイムコンテンツ、またはリクエストごとのコンテンツが混在する Next.js 16 のページを構築またはレビューするとき
• PPR（cacheComponents）を有効にする、または移行するとき、あるいは使われなくなった experimental.ppr ／ experimental_ppr のコードを見つけたとき
• <Suspense> 境界の配置場所を決めるとき、または Uncached data was accessed outside of <Suspense> ビルドエラーをデバッグするとき
• 'use cache'、cacheLife、cacheTag を追加するとき、またはミューテーション後に updateTag ／ revalidateTag ／ refresh のどれを使うか選ぶとき
• フォーム、複数ステップのウィザード、ダッシュボードを組み立てるとき、またはサーバーのデータをインタラクティブな Client Component にストリーミングするとき
• 実際に何がレンダリングされたかを実証的に検証またはデバッグするとき。静的シェルに含まれる部分とストリーミングされる部分、CSR／SSR の境界の位置、ルートが動的になった理由を調べるとき

ルールのカテゴリ

#	カテゴリ	接頭辞	対象
1	セットアップとメンタルモデル	setup-	cacheComponents による PPR の有効化、削除された実験的フラグ、デフォルトで動的／オプトインでのキャッシュという逆転
2	Suspense 境界	shell-	静的／動的の境目としての <Suspense>、ビルドエラー、境界の粒度、Suspense が行わないこと
3	'use cache' によるキャッシュ	cache-	ディレクティブのレベル、自動キー、実行時の値を props として渡す方法、受け渡し、cacheLife／cacheTag、サーバーレス環境での永続性
4	実行時 API と非決定性	runtime-	境界を必要とする非同期リクエスト API、generateStaticParams、ランダム性／時刻を扱う connection()
5	ページ構成のレシピ	compose-	単一の穴 → 並列ダッシュボード → Promise と use() によるストリーミング → アプリ全体をシェルから除外しない方法
6	フォーム、ミューテーション、ウィザード	mutate-	updateTag と revalidateTag と refresh の違い、URL によるウィザードのステップ管理、<Activity> によるフィールドの保持

クイックリファレンス

1. セットアップとメンタルモデル

• setup-enable-cache-components — cacheComponents: true による PPR の有効化。experimental.ppr ／ experimental_ppr フラグは削除されています
• setup-dynamic-by-default — すべての内容がリクエスト時にレンダリングされます。キャッシュは 'use cache' によるオプトイン方式です（fetch はキャッシュされなくなりました）

2. サスペンス境界

• shell-suspense-is-the-boundary — <Suspense> は静的シェルと動的ストリームの境界であり、スピナーではありません
• shell-wrap-uncached-data — キャッシュされていない／ランタイムでの読み取りは、ラップする（または 'use cache' を付ける）必要があります。そうしないとビルドエラーになります
• shell-suspense-does-not-force-dynamic — Suspense だけでは、同期処理は動的になりません
• shell-place-boundaries-low — ページ全体ではなく、動的な末端をラップして、シェルを大きく保ちます

3. 'use cache' によるキャッシュ

• cache-use-cache-directive — 関数／コンポーネント／ページ／レイアウト／ファイルのレベルで、静的／キャッシュ可能な処理を指定します
• cache-keys-are-automatic — 引数とクロージャでキャッシュキーが構成されるため、変化する入力は引数として渡します
• cache-pass-runtime-values-as-props — キャッシュされたスコープ内では cookies()／headers() を読み取れません。値を渡してください
• cache-pass-through-children-and-actions — 動的な children と Server Actions は、変更せずにキャッシュされたコンポーネントへ渡します
• cache-set-lifetime-and-tags — cacheLife で TTL を制御し、cacheTag でオンデマンドの無効化を有効にします
• cache-in-memory-not-durable-serverless — インメモリキャッシュはサーバーレス環境では永続性がありません。'use cache: remote' を使用してください

4. ランタイム API と非決定性

• runtime-request-apis-force-a-boundary — 非同期の cookies／headers／searchParams／params は、動的境界を強制します
• runtime-keep-param-routes-static — generateStaticParams により、[slug] ルートを静的シェル内に保てます
• runtime-gate-nondeterminism-with-connection — Math.random／Date.now／crypto は connection() の後に実行するか、値をキャッシュします

5. ページ構成のレシピ

• compose-single-dynamic-hole — 基本形：静的シェル＋1つの <Suspense> の穴
• compose-parallel-holes — ウィジェットごとに境界を1つ設けると、ウォーターフォールなしで並列ストリーミングできます
• compose-stream-to-client-with-use — await していない Promise を渡し、Client Component 内で use() によって値を取り出します
• compose-do-not-opt-out-the-shell — 境界エラーを回避するために、アプリ全体を遅延させないでください

6. フォーム、ミューテーション、ウィザード

• mutate-updatetag-vs-revalidatetag — updateTag（書き込み直後の読み取り）と revalidateTag(tag, profile)（SWR）、refresh() の違い
• mutate-wizard-url-driven-steps — URL 駆動のステップ＋静的なクローム＋<Activity> によるフィールドの保持

使用方法

該当する判断が必要になったら、リファレンスファイルを読んでください。各ルールでは、修正対象となる誤ったデフォルトを示したうえで、標準的な方法を説明します（誤った方法が実際の落とし穴である場合に限り、誤りと正解を対比します）。初めて取り組む場合は、まず setup- を読んでください。それ以外の内容は、動的がデフォルトという考え方を前提としています。

• セクションの定義 — カテゴリーの構成と順序
• 境界のデバッグ — next build と chrome-devtools-mcp（mcporter 経由）を使って、静的／動的境界とローディングを実証的に分析します。PPR の結果が予想外の場合や、blocking-route エラーの原因を調べる場合に使用します
• ルールのテンプレート — 新しいルールを追加するためのテンプレート
• AGENTS.md — すべてのルールを横断した自動生成の目次

関連スキル

• nextjs — Next.js 16 App Router の幅広いベストプラクティス（キャッシュ、サーバーコンポーネント、ルーティング、衛生管理）
• opinionated-nextjs-patterns — これらの PPR パターンを使用する、包括的で独自のアーキテクチャ（データレイヤー、ミューテーション、クライアント境界）
• react-fetch-cache-patterns — データ量の多い React UI 向けのリクエストオーケストレーションとクライアント側のキャッシュ

参照ファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
references/_debug-boundaries.md	実証に基づく CSR/SSR 境界とローディングのデバッグ（next build + mcporter 経由の chrome-devtools-mcp）
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとソースの参照