Next.js 16 アーキテクチャ — Turbopack と Cache Components を深く見る

app/
├── layout.tsx          ← ルートレイアウト（全ページ共通、サーバーコンポーネント）
├── page.tsx            ← "/" ルートの入口
├── loading.tsx         ← Suspense 境界のフォールバック UI
├── error.tsx           ← エラー境界（クライアントコンポーネント）
├── not-found.tsx       ← 404 処理
├── (marketing)/        ← ルートグループ（URL に影響なし）
│   └── about/
│       └── page.tsx    ← "/about"
└── dashboard/
    ├── layout.tsx      ← ネストレイアウト（dashboard 配下で共通）
    ├── page.tsx        ← "/dashboard"
    └── [id]/
        └── page.tsx    ← "/dashboard/:id" 動的セグメント

  ┌──────────────────────────────────────────────┐
  │                RootLayout                      │
  │  ┌──────────────────────────────────────────┐ │
  │  │            DashboardLayout                 │ │
  │  │  ┌────────────────┐  ┌──────────────────┐ │ │
  │  │  │  <ErrorBoundary>│  │ <Suspense>       │ │ │
  │  │  │   error.tsx    │  │   loading.tsx    │ │ │
  │  │  │      ▼          │  │      ▼            │ │ │
  │  │  │   page.tsx ────────────▶ レンダー結果   │ │ │
  │  │  └────────────────┘  └──────────────────┘ │ │
  │  └──────────────────────────────────────────┘ │
  └──────────────────────────────────────────────┘

サーバーコンポーネント（既定）       クライアントコンポーネント（"use client"）
────────────────────────           ──────────────────────────────
DB/ファイル/秘密への直接アクセス O   ブラウザ API / イベントハンドラ O
async/await データ取得          O   useState / useEffect フック     O
バンドルに JS を含む            X   バンドルに JS を含む            O
イベントハンドラ                X   サーバーの秘密へのアクセス       X

// server-page.tsx （サーバーコンポーネント）
import ClientShell from './client-shell'
import ServerWidget from './server-widget'

export default async function Page() {
  const data = await fetchData() // サーバーでのみ実行
  return (
    <ClientShell>
      {/* ServerWidget はサーバーでレンダーされ RSC ペイロードとして渡される */}
      <ServerWidget data={data} />
    </ClientShell>
  )
}

// client-shell.tsx
'use client'
import { useState } from 'react'

export default function ClientShell({ children }: { children: React.ReactNode }) {
  const [open, setOpen] = useState(false)
  // children（= ServerWidget）はすでに直列化された RSC ツリーで、再レンダーされない
  return <div onClick={() => setOpen((v) => !v)}>{open && children}</div>
}

[サーバーコンポーネント] ──直列化可能な props──▶ [クライアントコンポーネント]
       │                                              ▲
       └──── "use server" アクション参照 ─────────────┘
              （関数そのものではなく参照 ID を渡す）

┌─────────┬──────────────────────┬───────────────────┬───────────────┐
│ 戦略    │ 生成タイミング        │ キャッシュ         │ 適する場合     │
├─────────┼──────────────────────┼───────────────────┼───────────────┤
│ SSG     │ ビルド時              │ CDN 恒久          │ ブログ/文書    │
│ ISR     │ ビルド + 定期再生成   │ CDN + revalidate  │ 商品/ニュース  │
│ SSR     │ 毎リクエスト          │ なし（既定）       │ 個別化/リアル  │
│ PPR     │ 静的な殻 + 動的な穴   │ 殻は CDN、穴は     │ 混在ページ     │
│         │                       │ リクエスト時ストリーム │            │
└─────────┴──────────────────────┴───────────────────┴───────────────┘

リクエスト ──▶ [静的な殻を即送信（CDN キャッシュ）]
                ┌────────────────────────────────┐
                │ ヘッダー/ナビ/レイアウト（静的）  │  ◀── TTFB 非常に速い
                │  ┌──────────────────────────┐  │
                │  │ <Suspense>               │  │
                │  │   動的領域（リクエスト時） │  │  ◀── ストリーミングで
                │  │   例: ユーザーカート、推薦 │  │      続いて到着
                │  └──────────────────────────┘  │
                │ フッター（静的）                │
                └────────────────────────────────┘

// 関数単位のキャッシュ
async function getProducts(category: string) {
  'use cache'
  const res = await fetch(`https://api.example.com/products/${category}`)
  return res.json()
}

// コンポーネント単位のキャッシュ + 再検証タグ
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

async function ProductList({ category }: { category: string }) {
  'use cache'
  cacheLife('hours')        // キャッシュ寿命プロファイル
  cacheTag(`cat-${category}`) // タグベースの無効化
  const products = await getProducts(category)
  return <ul>{/* ... */}</ul>
}

                Cache Components の判定フロー
  ┌───────────────────────────────────────────────────┐
  │ コンポーネント/関数に 'use cache' があるか？        │
  └───────────────┬───────────────────┬───────────────┘
            はい（あり）           いいえ（なし）
                 ▼                     ▼
        ┌────────────────┐    ┌────────────────────┐
        │ 静的な殻に含む  │    │ 動的データに         │
        │ CDN/ビルドキャッシュ │    │ アクセスする？       │
        └────────────────┘    │ （cookies/headers） │
                              └─────┬──────────┬────┘
                            はい ▼         いいえ ▼
                        ┌──────────────┐  ┌──────────────┐
                        │ 動的な穴      │  │ 静的に処理可能 │
                        │ リクエスト時   │  │               │
                        │ ストリーム     │  │               │
                        └──────────────┘  └──────────────┘

import { revalidateTag } from 'next/cache'

export async function updateProduct(category: string) {
  'use server'
  await db.update(/* ... */)
  revalidateTag(`cat-${category}`) // そのタグが付いたキャッシュのみ無効化
}

   ブラウザ
     │  GET /dashboard/42
     ▼
 ┌─────────────────────────────────────────────────────────┐
 │                     Edge / CDN 階層                       │
 │  静的な殻のキャッシュ命中？ ──はい──▶ 即殻を返す（ストリーム）│
 │         │ いいえ                                          │
 └─────────┼───────────────────────────────────────────────┘
           ▼
 ┌─────────────────────────────────────────────────────────┐
 │                  Next.js サーバーランタイム               │
 │  1) ルートマッチング（app/dashboard/[id]/page.tsx）      │
 │  2) middleware 実行（認証/リダイレクト）                  │
 │  3) レイアウト → ページ RSC レンダー開始                  │
 │     ├─ 'use cache' 領域 → データキャッシュ照会            │
 │     └─ 動的領域 → データ取得（fetch/DB）                  │
 │  4) RSC ペイロード生成 + HTML ストリーミング              │
 └─────────┬───────────────────────────────────────────────┘
           ▼
 ┌─────────────────────────────────────────────────────────┐
 │                  データ / キャッシュ階層                  │
 │  Data Cache（fetch 結果）· Full Route Cache（RSC）        │
 │  外部 DB / API / ファイルシステム                         │
 └─────────────────────────────────────────────────────────┘
           ▼
   ブラウザ: HTML ストリーム受信 → ハイドレーション → 操作可能

┌────────────────────────────────────────────────────────────┐
│  1. Router Cache（クライアントメモリ）                       │
│     - 訪問したルートの RSC ペイロードをブラウザに保持        │
│     - 戻る/prefetch 時に即レンダー                          │
├────────────────────────────────────────────────────────────┤
│  2. Full Route Cache（サーバービルド/ランタイム）            │
│     - 静的ルートの RSC + HTML 結果                           │
├────────────────────────────────────────────────────────────┤
│  3. Data Cache（サーバー、永続）                             │
│     - fetch 結果 / 'use cache' 関数の結果                    │
│     - cacheLife / revalidateTag で制御                       │
├────────────────────────────────────────────────────────────┤
│  4. Request Memoization（単一リクエスト寿命）                │
│     - 同一リクエスト内の同一 fetch を重複排除                │
└────────────────────────────────────────────────────────────┘

        webpack（従来）              Turbopack（Rust）
  ──────────────────────────    ──────────────────────────
  JS ベース、ほぼ単一スレッド    Rust マルチコア並列処理
  グラフ全体を再計算しがち       関数単位の増分キャッシュ
  大きなアプリほど起動が遅い     要求したルートのみオンデマンドコンパイル
  HMR は漸進的                  変更分のみ最小再計算

   ファイル変更（button.tsx）
          │
          ▼
   ┌──────────────────────────────┐
   │ 依存グラフで影響を追跡         │
   │ button.tsx → toolbar.tsx →    │
   │             page.tsx          │
   └──────────────┬───────────────┘
                  ▼
   影響を受けたノードのみ無効化して再計算
   （グラフの残りはキャッシュのまま）
                  │
                  ▼
   HMR パッチをブラウザへ送信

// 変更後のパターン
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  return <div>{id}</div>
}

[ ] クライアントコンポーネントにサーバー専用モジュール（fs, db）を import していないか
[ ] サーバー→クライアントの props がすべて直列化可能か（関数/クラスを除く）
[ ] 'use client' 境界を上に置きすぎてバンドルが肥大化していないか
[ ] 動的データ（cookies/headers）アクセス領域を Suspense で包んだか
[ ] revalidateTag のタグ文字列が cacheTag と正確に一致するか
[ ] 環境変数の NEXT_PUBLIC_ 接頭辞の有無を混同していないか

悪い例                          良い例
─────────────                   ─────────────
RootLayout（"use client"）      RootLayout（server）
   └─ すべてクライアントバンドル     └─ Page（server）
                                      └─ LikeButton（"use client"）
                                         ← インタラクションの葉のみクライアント

/dashboard/[id]
 ├─ Layout（静的、'use cache'）           ← ナビ/サイドバー
 ├─ ProfileHeader（動的: cookies 使用）    ← ユーザー別、Suspense の穴
 ├─ StatsPanel（'use cache'、cacheLife）   ← 5分キャッシュ、共有統計
 └─ ActivityFeed（動的: リアルタイム）      ← ストリーミング、Suspense の穴