next-best-practices

Next.js のレビューと実装

フレームワークの動作を変更する前に、インストールされている next のバージョンと、関連する node_modules/next/dist/docs/ のページを確認してください。これらのドキュメントとプロジェクトの設定を優先してください。ローカルのドキュメントを参照できない場合は、対応するオンライン版またはソースタグを使用してください。Next.js は vercel/next.js の skills/ でワークフロースキルを公開しています。

ドキュメントは 16.2 から同梱されています。モノレポでは、アプリ固有の next パッケージを確認してください。これらのファイルに記載された nextjs.org のリンクには、番号付きフォルダー内にローカルの対応ファイルがあります。ファイル名で検索してください（find node_modules/next/dist/docs -name proxy.md）。 01-app/02-guides/upgrading/version-16.md に破壊的変更が記載されています。 エラーごとのページ（/docs/messages/*）はオンラインでのみ参照できます。開発／ビルドの出力には、そのエラーの修正方法が表示されます。 正確なエクスポート内容は node_modules/next/{server,navigation,headers,cache}.d.ts にも記載されています。

他の作業に着手する前に、インストールされているバージョンを Next.js のセキュリティ勧告と照合し、影響を受ける場合はユーザーに伝えてください。2026-10-22 時点では、16.0.0～16.4.0（16.4.1 で修正）および 15.5.27 までの 15.x（15.5.28 で修正）には、重大な RCE があります。該当するのは、型付き配列を返す use cache 関数（GHSA-673q-mjm6-r5xr、16.x のみ、回避策なし）と、glibc Linux 上でセルフホストしている場合の SVG の画像最適化（GHSA-2464-fhr4-w9xw。暫定的な修正策は sharp 0.35.5+）です。また、Server Actions の DoS（GHSA-p3m5-59mp-jv5r）もあります。16.4 以降では、experimental.agentUpgrade（デフォルトは 'security'）により、next dev／next build の実行時に注意が表示されます。16.3.x 以前では、この注意は表示されません。

Next.js 16 で変更された、古い例では対応できない点

• 同期的なリクエスト情報へのアクセスは削除されました。cookies()、headers()、draftMode()、params（画像メタデータのルートを含む）、searchParams、サイトマップの id はすべてプロミスです。next typegen はグローバルな PageProps<'/route'>、LayoutProps、RouteContext 型を生成します。
• middleware.ts は非推奨です。proxy（または default）をエクスポートする proxy.ts は Node.js 上でのみ実行され、runtime オプションを拒否します。Edge を必要とするコードは middleware.ts に残してください。Codemod：npx @next/codemod@latest middleware-to-proxy .。
• dev と build では Turbopack がデフォルトになりました。カスタムの webpack 設定があると、--webpack で維持するか、明示的な --turbopack で無視しない限り、ビルドは失敗します。next lint は削除され、next build では lint が実行されなくなりました。serverRuntimeConfig／publicRuntimeConfig は削除されました。
• 並列ルートの各スロットには default.tsx が必要です。ない場合、ビルドは失敗します。
• next/image：priority は非推奨となり、preload を使用します。qualities のデフォルトは [75] です（その他の quality 値は強制的に変換されます）。クエリ文字列を含むローカルの src には images.localPatterns が必要です。images.domains は非推奨となり、remotePatterns を使用します。
• revalidateTag(tag) は非推奨です。即時に期限切れにするには、'max' などのプロファイル、または { expire: 0 } を渡してください。updateTag と refresh は Server Action でのみ使用できます。キャッシュの詳細については cache-components を参照してください。

next 16.3.8 で確認済みの params と proxy の形式（next typegen、tsc --noEmit、next build）：

// app/blog/[slug]/page.tsx; PageProps is global after `next typegen` (or dev/build)
export async function generateStaticParams() {
  return [{ slug: 'hello' }] // cacheComponents: needed for this top-level await; never []
}

export default async function Page({ params }: PageProps<'/blog/[slug]'>) {
  const { slug } = await params // a Promise; sync access was removed in 16
  return <h1>{slug}</h1>
}

// proxy.ts, replacing middleware.ts: Node.js runtime, no `runtime` export
import { NextResponse, type NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  // Optimistic check only: authorize again where the data is read.
  if (request.cookies.has('session')) return NextResponse.next()
  return NextResponse.redirect(new URL('/login', request.url))
}

export const config = { matcher: ['/dashboard/:path*'] }

upgrade codemod は、同期的なリクエスト API へのアクセスを移行しません。そのコードを移行する場合は、別途 next-async-request-api を実行してください。プロジェクトのパッケージランナーを使用し、生成された型と実行時の動作を確認してください。

承認を得てアップグレードする場合、npx next@canary upgrade [app-dir] --agent=security（または =latest。実験的機能で、インストール済みの 02-guides/upgrading/agent-upgrade.md では 16.4 以降の内容として説明されています）は、アップグレード先を選択し、現在のエージェント向けのガイド、codemod、チェック項目を表示します。通常の next upgrade を実行すると、対話形式の codemod が実行されます。

すべての最適化を適用するのではなく、実際に発生している障害や必要な機能を確認してください。移行が依頼されていない限り、プロジェクトのルーター、キャッシュモード、ランタイム、パッケージマネージャーを維持してください。

影響を受ける領域を参照する

領域	ローカルの参照資料
ルートファイル、グループ、プロキシ	ファイルの規約
サーバー／クライアントのインポートと props	RSC の境界、ディレクティブ
パラメーターとリクエスト API	非同期 API、関数
読み取り、ミューテーション、API	データパターン、ルートハンドラー
レンダリングとエラー	Suspense、ハイドレーション、エラー
メタデータと公開情報の検出	メタデータ；SEO 監査には nextjs-seo
アセットと読み込み	画像、フォント、スクリプト
パッケージ／ランタイムの動作	バンドル、ランタイム
ナビゲーションのスロット／モーダル	並列ルート
デプロイ／デバッグ	セルフホスティング、診断

そのモードが有効で、タスクに関連する場合は cache-components を使用してください。 タグによる無効化は、そのモード以外の fetch キャッシュにも適用できます。

プロジェクトの lint／typecheck スクリプトと本番ビルドで検証し、 変更したルートを next start でテストしてください。開発環境でのレンダリングでは、 プリレンダリングや Suspense の問題が隠れることがあります。ビルドだけでは、認可、ハイドレーション、 鮮度、インスタンス間の動作を証明できません。実際にテストした内容を報告してください。