nextjs-16-complete-guide

Next.js 16 完全ガイド

目的

Next.js 16 の革新的な機能を包括的に解説します。「use cache」によるキャッシュコンポーネント、デフォルトのバンドラーとして安定版になった Turbopack、proxy.ts アーキテクチャ、DevTools MCP との統合、React Compiler のサポートを取り上げます。

使用する場面

• 新しい Next.js プロジェクトを始めるとき（初日から 16 を使用）
• Next.js 15 から 16 に移行するとき
• キャッシュコンポーネントと部分的なプリレンダリング（PPR）を理解するとき
• 最適なパフォーマンスを得るために Turbopack を設定するとき
• middleware.ts から proxy.ts に移行するとき
• DevTools MCP を使って AI 支援デバッグを活用するとき
• 自動メモ化のために React Compiler を設定するとき

変更点：Next.js 15 → 16

全体像

Next.js 15 は移行期でした。非同期 API、実験的な Turbopack、変わりゆくキャッシュのデフォルト設定がありました。 Next.js 16 は成果を得る段階です。すべてが安定し、高速になり、本番環境に対応します。

主な違い

機能	Next.js 15	Next.js 16
バンドラー	Webpack（デフォルト）、Turbopack（オプトインのベータ版）	Turbopack（デフォルト、安定版）
キャッシュ	暗黙的で、デフォルト設定がわかりにくい	「use cache」で明示的に指定
ネットワーク層	middleware.ts（エッジランタイム）	proxy.ts（Node.js ランタイム）
DevTools	基本的なエラーメッセージ	AI デバッグのための MCP 統合
React Compiler	実験的	安定版、本番環境に対応
パフォーマンス	ベースライン	ビルドが 2～5 倍高速、Fast Refresh が 10 倍高速

---

🚀 コア機能（20% で 80% の成果を実現）

1. キャッシュコンポーネント + 「use cache」

Next.js 15 の問題：

• 暗黙的なキャッシュは「魔法」のようで、何がキャッシュされるか予測しにくい
• 静的と動的の切り替えが不明瞭
• パフォーマンス最適化が当てずっぽうに感じられる

Next.js 16 の解決策：

// Enable in next.config.ts
const nextConfig = {
  cacheComponents: true,
};

export default nextConfig;

使用パターン：

// app/dashboard/page.tsx
import { Suspense } from 'react';

// This component caches its output
async function UserMetrics() {
  'use cache'; // 🎯 Explicit caching

  const metrics = await fetchMetrics(); // Cached result

  return <MetricsCard data={metrics} />;
}

// This stays dynamic
async function LiveBalance() {
  const balance = await fetchBalance(); // Always fresh
  return <BalanceWidget balance={balance} />;
}

export default function Dashboard() {
  return (
    <div>
      <Suspense fallback={<LoadingMetrics />}>
        <UserMetrics /> {/* Cached, instant load */}
      </Suspense>

      <LiveBalance /> {/* Dynamic, real-time */}
    </div>
  );
}

重要な理由：

• 即時ナビゲーション - キャッシュされた部分をすぐに読み込みます
• 選択的な最新性 - 動的な部分だけを必要に応じて取得します
• 予測可能な動作 - 何をキャッシュするかを制御できます
• SaaS ダッシュボード - 静的コンテンツと動的コンテンツが混在するパネルに最適です

キャッシュの粒度：

// Cache entire page
export default async function Page() {
  'use cache';
  return <PageContent />;
}

// Cache individual component
async function ExpensiveWidget() {
  'use cache';
  return <Chart data={await getData()} />;
}

// Cache function result
async function getStats() {
  'use cache';
  return await database.query('...');
}

---

2. Turbopack：デフォルトのバンドラー（安定版）

パフォーマンスの数値（Vercel 公式ベンチマーク）：

• 本番ビルドが 2～5 倍高速
• 開発時の Fast Refresh が最大 10 倍高速
• ファイルシステムキャッシュ - 大規模プロジェクトでは再起動がさらに高速になります

設定は不要：

// next.config.ts
// Turbopack is now default - no config required!

無効化する場合：

# Use Webpack instead
next build --webpack

ファイルシステムキャッシュ（ベータ版）：

// next.config.ts
const nextConfig = {
  experimental: {
    turbopackFileSystemCacheForDev: true, // Faster restarts
  },
};

重要な理由：

• フィードバックループの高速化 - 変更をすぐに確認できます（10 倍高速）
• CI/CD の時間短縮 - 本番ビルドが 2～5 倍高速になります
• より良い開発体験 - 待ち時間を減らし、リリースを増やせます
• 大規模プロジェクト - Webpack よりも優れたスケーラビリティを発揮します

実感できること：

# Before (Webpack)
✓ Compiled in 4.2s

# After (Turbopack)
✓ Compiled in 0.4s  # 10× faster

---

3. middleware.ts を proxy.ts に置き換え

変更点：

# Old (Next.js 15)
middleware.ts  # Edge runtime, confusing

# New (Next.js 16)
proxy.ts       # Node.js runtime, explicit

移行例：

// OLD: middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url));
}

export const config = {
  matcher: '/about/:path*',
};

// NEW: proxy.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export default function proxy(request: NextRequest) {  // Changed function name
  return NextResponse.redirect(new URL('/home', request.url));
}

export const config = {
  matcher: '/about/:path*',
};

主な変更点：

1. ファイル名を変更：middleware.ts → proxy.ts
2. エクスポート名を変更：export function middleware → export default function proxy
3. ランタイム：Node.js 上で実行（エッジではありません）

重要な理由：

• 境界が明確 - 「Proxy」はネットワークの入口を意味します
• 予測可能なランタイム - 常に Node.js で、エッジかどうかの曖昧さがありません
• デバッグの改善 - 標準的な Node.js 環境でデバッグできます

---

4. DevTools MCP（AI 支援デバッグ）

できること： Next.js 16 は Model Context Protocol（MCP）を統合し、AI エージェントが次の操作を行えるようにします。

• ブラウザーとサーバーの統合ログを読み取る
• Next.js のルーティングとキャッシュを理解する
• エラーのスタックトレースに自動でアクセスする
• ページを認識したデバッグコンテキストを提供する

重要な理由：

• AI コパイロットが Next.js アプリをネイティブにデバッグできます
• デバッグの高速化 - AI がフレームワークの内部を理解します
• より良い開発体験 - エージェントはあなたが見ているもの（それ以上も）を把握します

使用例：

You: "Why is this page not caching?"
AI Agent (with MCP):
  - Reads server logs
  - Sees route configuration
  - Checks cache headers
  - Knows Next.js 16 caching rules
  → "You're missing 'use cache' directive in your component"

統合： Claude Code、Cursor、その他の MCP 対応ツールで自動的に動作します。

5. React Compiler（安定版）

機能： コンポーネントを自動的にメモ化し、手動での useMemo、useCallback、React.memo が不要になります。

セットアップ：

npm install babel-plugin-react-compiler@latest

// next.config.ts
const nextConfig = {
  reactCompiler: true,  // Moved from experimental to stable
};

変更前（手動で最適化）：

// You had to do this everywhere
const MemoizedComponent = React.memo(function Component({ data }) {
  const processed = useMemo(() => processData(data), [data]);
  const handleClick = useCallback(() => {
    console.log(processed);
  }, [processed]);

  return <div onClick={handleClick}>{processed}</div>;
});

変更後（React Compiler が自動で処理）：

// Just write code, compiler optimizes automatically
function Component({ data }) {
  const processed = processData(data);  // Auto-memoized
  const handleClick = () => {            // Auto-memoized
    console.log(processed);
  };

  return <div onClick={handleClick}>{processed}</div>;
}

重要な理由：

• 定型コードの削減 - よりすっきりしたコードを書けます
• パフォーマンスの向上 - コンパイラーは手動の最適化より賢く処理します
• バグの防止 - コンパイラーは依存関係を見落としません

---

🔥 破壊的変更（15 → 16）

必須の変更

1. Node.js のバージョン

# Minimum: Node.js 20.9+
# Next.js 15: Node.js 18 worked
# Next.js 16: Node.js 18 no longer supported

2. 非同期の params と searchParams

// ❌ OLD (Next.js 15)
export default function Page({ params, searchParams }) {
  const id = params.id;  // Synchronous
}

// ✅ NEW (Next.js 16)
export default async function Page({ params, searchParams }) {
  const { id } = await params;  // Must await
  const { query } = await searchParams;
}

3. 非同期の cookies()、headers()、draftMode()

// ❌ OLD
import { cookies } from 'next/headers';

export function MyComponent() {
  const token = cookies().get('token');  // Synchronous
}

// ✅ NEW
import { cookies } from 'next/headers';

export async function MyComponent() {
  const cookieStore = await cookies();  // Must await
  const token = cookieStore.get('token');
}

4. revalidateTag() に cacheLife プロファイルが必須に

// ❌ OLD
revalidateTag('posts');

// ✅ NEW
revalidateTag('posts', 'max');     // Options: 'max', 'hours', 'days'

5. middleware.ts → proxy.ts

# Required migration
mv middleware.ts proxy.ts

# Update function name
export default function proxy(request) { ... }

削除された機能

• AMP のサポート - 完全に削除されました
• next lint コマンド - 削除されました
• Node.js 18 - サポート対象外になりました
• TypeScript <5.1 - サポート対象外になりました

---

📦 移行ガイド（手順ごと）

1. 移行前のチェックリスト

# Check current versions
node --version    # Should be 20.9+
npm list next     # Current Next.js version
npm list react    # React version

2. 自動移行

# Upgrade to latest Next.js 16
npm install next@latest react@latest react-dom@latest

# Run codemod (handles most changes automatically)
npx @next/codemod@canary upgrade latest

3. 手動での変更

next.config を更新：

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  // Enable Cache Components
  cacheComponents: true,

  // Enable React Compiler
  reactCompiler: true,

  // Optional: File system caching
  experimental: {
    turbopackFileSystemCacheForDev: true,
  },
};

export default nextConfig;

middleware の名前を変更：

# If you have middleware.ts
git mv middleware.ts proxy.ts

# Update function name in proxy.ts
export default function proxy(request: NextRequest) {
  // Your logic
}

非同期 API を更新：

// Search codebase for:
// - params.
// - searchParams.
// - cookies()
// - headers()
// - draftMode()

// Add await before each

4. すべてをテスト

# Development
npm run dev  # Should use Turbopack automatically

# Production build
npm run build  # Should be 2-5× faster

# Run tests
npm test

5. デプロイ

# Verify Node.js version in production
# Deploy to Vercel/platform
# Monitor for errors in first 24h

---

🎯 ベストプラクティス

1. 新しいプロジェクトでは Next.js 16 を使う

npx create-next-app@latest my-app
# Automatically uses Next.js 16, Turbopack, TypeScript, Tailwind

2. 「use cache」を戦略的に使う

// ✅ Good: Cache expensive, infrequent-changing data
async function MonthlyReport() {
  'use cache';
  return await generateReport();
}

// ❌ Bad: Don't cache user-specific real-time data
async function CurrentBalance() {
  'use cache';  // Wrong! This should be fresh
  return await getUserBalance();
}

3. ビルドのパフォーマンスを監視する

# Next.js 16 shows detailed timing
npm run build

# Example output:
Route (app)                              Size     First Load JS
┌ ○ /                                   142 B          87.2 kB
├ ○ /_not-found                         142 B          87.2 kB
└ ○ /dashboard                          1.23 kB        88.4 kB

Build time: 14.2s  # Was 57s in Next.js 15 with Webpack

4. DevTools MCP を活用する

• MCP をサポートする Claude Code / Cursor を使います
• AI エージェントに Next.js の内部を読み取らせます
• 「ページが遅いのはなぜですか？」と質問します。エージェントはサーバーログを確認できます

5. 大規模なアプリで React Compiler を有効にする

// Only if you have performance issues
reactCompiler: true

---

📊 アップグレードするタイミング（判断基準）

✅ 今すぐアップグレードする場合：

• 新しいプロジェクトを始める（初日から 16 を使う）
• 小規模または中規模のコードベース（ルート数 50 未満）
• Vercel を使っている（テスト済みのプラットフォーム）
• ビルドを 2～5 倍高速化したい
• 即時のナビゲーションが必要（Cache Components）

⏳ 1～2 週間待つ場合：

• 大規模な本番アプリ（ルート数 100 超）
• middleware.ts を多用している（proxy.ts への移行が必要）
• カスタム Webpack 設定を使っている
• サードパーティーライブラリがまだ対応していない
• デプロイ方針としてリスクを避けたい

🚫 まだアップグレードしない場合：

• AMP ページを使っている（16 で削除）
• Node.js 18 から移行できない
• カスタムビルドパイプラインを使っている（アダプターのテストが必要）
• 本番環境で実験的な機能を使っている

---

🔗 リソース

• Next.js 16 リリースノート
• アップグレードガイド
• Turbopack ドキュメント
• Cache Components ガイド
• Codemod CLI

---

💡 クイックリファレンス

インストール

npm install next@latest react@latest react-dom@latest

機能を有効にする

// next.config.ts
const nextConfig = {
  cacheComponents: true,           // Cache Components
  reactCompiler: true,             // React Compiler
  experimental: {
    turbopackFileSystemCacheForDev: true,  // Faster dev restarts
  },
};

移行チェックリスト

• Node.js 20.9+ をインストール済み
• npm install next@latest
• npx @next/codemod@canary upgrade latest を実行
• middleware.ts → proxy.ts に名前を変更
• params/searchParams/cookies/headers に await を追加
• revalidateTag() の呼び出しを cacheLife で更新
• ビルドをテスト：npm run build
• 開発環境をテスト：npm run dev
• まずステージング環境にデプロイ

---

要約： Next.js 16 は 15 での約束を果たします。あらゆる処理が高速化され、より明示的になり、本番環境ですぐに使えるようになりました。Turbopack はデフォルトとなり、キャッシュの動作は予測しやすく、AI ツールは標準で利用できます。2025 年に最新の SaaS アプリケーションを構築するなら、このバージョンがおすすめです。