【Next.js 16】paramsもcookiesも全部非同期！？ハマる前に読むBreaking Changes対応ガイド

AI Assisted
この記事は筆者の実装経験をもとに実装コードをベースで執筆し、AIによる校閲・推敲を経て公開しています。

Next.js 16 へのメジャーアップグレードでは、paramsやcookiesの非同期化、middleware.tsの廃止など、既存のアプリケーションに大きな影響を与える変更が含まれています。 何も知らずにアップグレードすると、大量のエラーに直面することになります。

この記事では、Next.js 16 における Breaking Changes（破壊的変更）の全貌と、具体的な対応方法をコード付きで解説します。

---

Breaking Changes とは

後方互換性のない変更のことです。アップグレードすると、今まで動いていたコードが動かなくなる可能性がある変更を指します。

Next.js はメジャーバージョンアップ時に、設計の改善、セキュリティ修正、パフォーマンス向上などを目的として Breaking Changes を導入します。今回は特に大規模な変更が含まれているため、事前の把握が必須です。

---

動作環境の変更

まず、足回りの環境を確認しましょう。

Node.js 20.9 以上が必須

Node.js 18 はサポート対象外になりました。

# バージョン確認
node -v

# nvm 使用時
nvm install 20
nvm use 20

CI/CD、Docker、本番環境すべてで確認とアップデートが必要です。

TypeScript 5.1 以上が必須

TypeScript を使用している場合は、package.json のバージョンを確認してください。

---

【重要】必須対応事項

ここが今回のアップグレードで最も影響が大きい部分です。多くのコンポーネントで修正が必要になります。

1. params / searchParams の非同期化

Page や Layout コンポーネントの props である params と searchParams が Promise になりました。アクセスするには await が必要です。

// [NG] Next.js 15まで
export default function Page({ params }: { params: { id: string } }) {
  // 同期的にアクセスできていた
  const { id } = params
  return <div>{id}</div>
}

// [OK] Next.js 16から
export default async function Page({
  params,
}: {
  // 型も Promise になる
  params: Promise<{ id: string }>
}) {
  // await が必須
  const { id } = await params
  return <div>{id}</div>
}

クエリパラメータを取得する searchParams も同様です。

// [OK] Next.js 16
export default async function Page({
  searchParams,
}: {
  searchParams: Promise<{ q?: string }>
}) {
  const { q } = await searchParams
  return <div>検索: {q}</div>
}

2. cookies / headers / draftMode の非同期化

サーバーサイドでリクエスト情報を取得する関数群も非同期になりました。

// [NG] Next.js 15まで
import { cookies, headers, draftMode } from 'next/headers'

export default function Page() {
  const cookieStore = cookies() // 同期
  const headerList = headers() // 同期
  const { isEnabled } = draftMode() // 同期
}

// [OK] Next.js 16から
import { cookies, headers, draftMode } from 'next/headers'

// コンポーネントを async にする
export default async function Page() {
  const cookieStore = await cookies() // 非同期
  const headerList = await headers() // 非同期
  const { isEnabled } = await draftMode() // 非同期
}

3. middleware.ts → proxy.ts

従来の Middleware は廃止され、より強力な proxy.ts に置き換わりました。ファイル名と関数名の変更が必要です。

詳細は別記事「Next.js 16 proxy.ts 移行ガイド」を参照してください。

// [NG] Next.js 15: middleware.ts
export function middleware(request: NextRequest) { ... }

// [OK] Next.js 16: proxy.ts
export function proxy(request: NextRequest) { ... }

4. 並列ルートの default.js が必須

並列ルート（@folder）を使用している場合、すべてのスロットに対してフォールバック用の default.tsx（または default.js）が必須になりました。

app/
├── @sidebar/
│   ├── page.tsx
│   └── default.tsx  <- これがないとエラーになる
├── layout.tsx
└── page.tsx

とりあえず何も表示しない場合は null を返します。

// app/@sidebar/default.tsx
export default function Default() {
  return null
}

---

画像最適化の変更

next/image のデフォルト設定がいくつか変更されています。意図しない表示崩れやキャッシュ挙動の変化に注意してください。

デフォルト値の変更

従来の動作を維持したい場合は、next.config.js で明示的に設定する必要があります。

// next.config.js
const nextConfig = {
  images: {
    // Next.js 15 と同じ挙動にする設定例
    minimumCacheTTL: 60,
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
    qualities: [50, 75, 100],
    maximumRedirects: 5,
  },
}

ローカル IP の制限

セキュリティ強化のため、ローカル IP への画像最適化リクエストがデフォルトでブロックされるようになりました。開発環境などで許可したい場合は設定が必要です。

// next.config.js
const nextConfig = {
  images: {
    dangerouslyAllowLocalIP: true,
  },
}

クエリ文字列付きローカル画像

クエリ文字列（?v=1 など）を含むローカル画像を最適化する場合、localPatterns.search の設定が必須になりました。

// next.config.js
const nextConfig = {
  images: {
    localPatterns: [
      {
        pathname: '/assets/**',
        search: '?v=1', // クエリを許可
      },
    ],
  },
}

---

Turbopack の変更

デフォルトバンドラーに

待望の Turbopack が、next dev と next build のデフォルトバンドラーになりました。高速な開発体験が標準になります。

# Turbopack で起動（デフォルト）
next dev
next build

# 従来の webpack に戻す場合
next dev --webpack
next build --webpack

設定の場所が変更

next.config.js 内での Turbopack の設定場所が、experimental からトップレベルに移動しました。

// [NG] Next.js 15
const nextConfig = {
  experimental: {
    turbopack: { /* options */ },
  },
}

// [OK] Next.js 16
const nextConfig = {
  turbopack: { /* options */ },
}

出力ディレクトリの分離

next dev と next build の出力先が分離されました。

これにより、開発サーバーを起動したまま裏でビルドを実行する、といった並行作業が可能になります。

---

削除された機能

以下の機能は完全に削除されました。使用している場合は代替手段への移行が必要です。

AMP サポート

AMP 関連のすべての API が削除されました。

// [NG] 削除されたAPI
import { useAmp } from 'next/amp'
export const config = { amp: true }

next lint コマンド

Next.js 組み込みのリンターコマンドが削除されました。今後は標準的な ESLint CLI や他のツールを使用します。

# [NG] 削除
next lint

# [OK] 代替案
npx eslint .
# または
npx biome check .

Runtime Configuration

serverRuntimeConfig と publicRuntimeConfig は削除されました。

// [NG] 削除
module.exports = {
  serverRuntimeConfig: { ... },
  publicRuntimeConfig: { ... },
}

今後は標準的な環境変数（.env）を使用してください。

# .env.local
DATABASE_URL=xxx           # サーバー側のみで参照可能
NEXT_PUBLIC_API_URL=xxx    # クライアント側でも参照可能（NEXT_PUBLIC_ 接頭辞）

その他の削除

• devIndicators オプション（ビルドインジケーターの表示設定）
• experimental.dynamicIO（代わりに cacheComponents: true を使用）

---

非推奨になった機能

まだ動作はしますが、将来的に削除されるため移行が推奨される機能です。

next/legacy/image

// [注意] 非推奨
import Image from 'next/legacy/image'

// [OK] 推奨：新しい next/image を使う
import Image from 'next/image'

images.domains

画像最適化のドメイン指定は、よりセキュアな remotePatterns が推奨されます。

// [注意] 非推奨
const nextConfig = {
  images: {
    domains: ['example.com'],
  },
}

// [OK] 推奨
const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https', // プロトコル指定が必須
        hostname: 'example.com',
      },
    ],
  },
}

unstable_ プレフィックス

キャッシュ関連のAPIが安定化しました。

// [NG] 非推奨
import {
  unstable_cacheLife as cacheLife,
  unstable_cacheTag as cacheTag,
} from 'next/cache'

// [OK] 推奨
import { cacheLife, cacheTag } from 'next/cache'

---

その他の動作変更

細かいですが、挙動が変わる点です。

スクロール動作

Next.js はナビゲーション中に CSS の scroll-behavior: smooth をオーバーライドしなくなりました。 もしスムーズスクロールが効かなくなった場合は、自身の CSS または html タグで明示的に設定してください。

<html lang="ja" style={{ scrollBehavior: 'smooth' }}>

next.config.js のロード回数

開発時の設定ファイルロードが 2 回から 1 回に削減され、起動が高速化しました。 これに伴い、process.argv.includes('dev') は意図した動作をしなくなります。環境の判定には NODE_ENV を使用してください。

// [NG] 動作しない
if (process.argv.includes('dev')) { ... }

// [OK] 推奨
if (process.env.NODE_ENV === 'development') { ... }

ビルド出力のメトリクス削除

next build 実行時に表示されていた size（バンドルサイズ）と First Load JS のメトリクス表示が削除されました。 正確なパフォーマンス測定には、Chrome Lighthouse や Vercel Analytics などの専用ツールを使用してください。

---

自動マイグレーション (codemod)

手動での修正範囲が広いため、Next.js 公式が提供する codemod（自動修正ツール）の活用を強く推奨します。

以下のコマンドで、主要な破壊的変更を自動的に適用できます。

npx @next/codemod@canary upgrade latest

このコマンドは以下のような変更を自動で行ってくれます：

• async-request-api: params/searchParams/cookies 等の非同期化
• middleware-to-proxy: proxy.ts への移行
• next-lint-to-eslint-cli: ESLint CLI への移行設定

---

おすすめのアップグレード手順

1. パッケージ更新

まず、Next.js と React 関連のパッケージを最新版に更新します。

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

2. codemod 実行

自動修正ツールを実行し、機械的に直せる部分を一気に修正します。

npx @next/codemod@canary upgrade latest

3. 手動修正と確認

codemod で対応しきれない部分（画像設定の変更や、複雑なコンポーネントの非同期化など）を手動で修正します。TypeScript のエラーを頼りに修正していくと良いでしょう。

4. ビルドと動作確認

# まずビルドが通るか確認
npm run build

# 開発サーバーで実際の動作を確認
npm run dev

---

まとめ

Next.js 16 は、パフォーマンスと開発体験を大きく向上させるメジャーアップデートですが、その分、移行のハードルも高くなっています。

• Node.js 20.9+ / TypeScript 5.1+ が必須。
• params, cookies 等の完全非同期化（これが一番大変です）。
• middleware.ts は廃止され proxy.ts へ。
• Turbopack がデフォルトに。

特に非同期化の対応は、アプリケーション全体に影響が及びます。codemod を活用しつつ、計画的にアップグレードを進めてください。

---

参考リンク

• Next.js 16 Release Blog
• Upgrading to Version 16 (公式移行ガイド)
• Next.js Codemods