Next.js アップグレードプロトコル は何をしますか?
Next.js のバージョンアップグレード(例:v14 → v15)のための自動化および手動マイグレーション手順。
優先度: P1(運用)
実装ガイドライン
- アップグレード検出: 常に
package.jsonでnext、react、react-domのバージョンを確認します。 - 計画: メジャーバージョンが複数飛んでいる場合(v13 から v15 など)は、段階的アップグレード(v13 → v14、次に v14 → v15)を実施します。公式の Next.js 移行ガイド に従ってください。
- 自動化された Codemod:
npx @next/codemod@latest <transform> <path>を使用して構文移行を自動化します。 - 破壊的変更(v15):
next-async-request-api変換に対応し、params、searchParams、cookies()、headers()が await されていることを確認します。 - React のバージョン整合性: Next.js のピア依存関係に合わせて
reactとreact-domをアップグレードします(例:Next.js 15 では React 19)。 - 検証: 各段階的アップグレードの後に
next devとnext buildを実行します。コンソールエラー でハイドレーション警告がないか確認します。 - 報告: すべての codemod の失敗 や手動修正が必要な箇所をチームに報告します。
3. 依存関係の更新
Next.js とピア依存関係を同期してアップグレードします:
# npm を使用
npm install next@latest react@latest react-dom@latest
# 型定義の更新
npm install --save-dev @types/react@latest @types/react-dom@latest
4. 手動検証ルール
- 非同期コンテキスト:
cookies()、headers()、ルートのparamsがすべて await されていることを確認します。 - メタデータ:
generateMetadataの型が新しい非同期paramsシグネチャと一致することを確認します。 - キャッシュ: v15 以降では、
fetchのデフォルトは{ cache: 'no-store' }です。以前の動作が必要な場合は、明示的に{ cache: 'force-cache' }を設定します。
5. ビルドテスト
- codemod とパッケージ更新の直後に
npm run buildを実行します。 --turboを使用している場合、「Hydration failed」または「Turbopack」の互換性エラーがないか確認します。
アンチパターン
- メジャーバージョンのスキップ禁止: 一度に 1 メジャーバージョンずつアップグレードします(13→14、次に 14→15)。
- 手動による破壊的変更の修正禁止: 常に最初に
npx @next/codemod@latest変換を実行します。 - アップグレード後のキャッシュ動作を推測しない: v15 のデフォルトは
no-storeです。すべてのfetch呼び出しを監査します。 - Pages Router での非同期ページ関数禁止:
export default async function Page()は致命的です。