Next.js 16/React 19アップグレードで遭遇！HMRの罠と解決策

Posted at 2026-07-08

多くのNext.js開発者が経験するであろうHMR（Hot Module Replacement）の突然の停止。特に、Next.js 16とReact 19へのアップグレードを検討している、または既に試みている方にとって、これは非常に厄介な問題です。従来のHMRの挙動とは異なる、WebSocketベースの新しいHMRシステムへの移行は、思わぬ落とし穴を多数生み出します。

この記事では、Next.js 16とReact 19へのバージョンアップで遭遇する具体的なHMRの罠と、それ以外の破壊的変更に対する効果的な解決策を、コード例を交えて徹底解説します。この記事を読めば、あなたのプロジェクトのアップグレードをスムーズに進め、開発体験を損なうことなく最新のNext.jsとReactの恩恵を享受できるようになります。

Next.js 16 / React 19 アップグレードの前提と環境

このセクションでは、Next.js 16とReact 19へのアップグレードを行う上での基本的な前提知識と、推奨される開発環境について解説します。

次世代のWeb開発を担うNext.js 16とReact 19

Next.js 16とReact 19は、Web開発のパラダイムを大きく変える重要なリリースです。

Next.js 16の主な特徴:

リリース予定日: 2025年10月21日（プレビュー版情報に基づく）
Turbopackの安定版化: 開発・プロダクションビルドのデフォルトバンドラーとなり、Fast Refreshが最大10倍、プロダクションビルドが2〜5倍高速化されます。（Next.js 公式ドキュメント - Turbopack）
キャッシュコンポーネント: use cacheディレクティブにより、キャッシュの制御が明示的になります。Partial Pre-Rendering (PPR) の概念を完成させ、静的コンテンツと動的コンテンツを組み合わせたページで高速な初期ロードとスムーズな更新を実現します。（Next.js 公式ドキュメント - Caching）
ルーティングとナビゲーションシステムの刷新: より柔軟で強力なルーティングが可能になります。
React Compilerの安定版サポート: パフォーマンス最適化が自動化されます。
middleware.tsからproxy.tsへの名称変更。（Next.js 16 Release Notes）

React 19の主な特徴:

安定版リリース日: 2024年12月5日
Actions: フォーム送信やサーバーミューテーションを簡素化する新しいパラダイム。
新しいHooks: useActionState、useOptimistic、use()など、非同期処理や状態管理を効率化します。（React 19 Release Notes）
Server ComponentsとServer Actionsの安定版: クライアント側のJavaScriptバンドルサイズを削減し、初期ロード時間を短縮します。
React Compiler: 自動的なパフォーマンス最適化。
コンポーネント内でのドキュメントメタデータ管理: <title>, <meta>タグなどをコンポーネント内で直接管理できるようになります。

必須の最小要件とアップグレードコマンド

Next.js 16とReact 19へのアップグレードには、以下の最小要件とアップグレードコマンドを使用します。

Node.js: 20.9以上
TypeScript: 5.1以上

アップグレードコマンド:

# Next.js 16へのアップグレード（Next.jsのcodemodツールを使用）
npx @next/codemod@canary upgrade latest

# または手動で
npm install next@latest react@latest react-dom@latest

# React 19へのアップグレード
npm install --save-exact react@^19.0.0 react-dom@^19.0.0

# TypeScriptを使用している場合、型定義も更新
npm install --save-exact @types/react@^19.0.0 @types/react-dom@^19.0.0

@next/codemod@canary upgrade latestコマンドは、Next.jsの多くの破壊的変更を自動的に修正しようとしますが、手動での確認と調整は必須です。

HMRの罠：WebSocket接続とトラブルシューティング

このセクションでは、Next.js 16へのアップグレードで最も遭遇しやすい問題の一つであるHMRの不具合、特にWebSocket接続に関する問題と、その具体的な解決策に焦点を当てます。

Next.js 16におけるHMRの変更点

Next.js 16では、Turbopackがデフォルトのバンドラーとなり、HMRの基盤も進化しています。これにより、従来のWebpackベースのHMRとは異なる挙動を示すことがあります。特に、HMRの通信がWebSocketを介して行われるため、WebSocket接続が阻害される環境ではHMRが機能しなくなる可能性があります。

ブラウザのデベロッパーツールでネットワークタブを確認し、ws://localhost:3000/_next/webpack-hmrのようなWebSocket接続がエラーになっていないか確認することが重要です。

HMRが機能しない場合の一般的な原因と回避策

HMRが機能しない場合、いくつかの一般的な原因が考えられます。

1. `.next`フォルダや`node_modules`の破損

最も単純で効果的な解決策です。開発サーバーを長時間稼働させたり、強制終了したりすると、一時ファイルが破損することがあります。

# 開発サーバーを停止
# Ctrl+C

# .nextフォルダとnode_modulesを削除
rm -rf .next node_modules

# 依存関係を再インストール
npm install

# 開発サーバーを再起動
npm run dev

2. WSL2環境特有のファイルシステム監視問題

WSL2 (Windows Subsystem for Linux 2) を使用している場合、Windows側のファイルシステムからLinux環境のプロジェクトを操作すると、ファイル変更イベントが適切に伝播されないことがあります。

回避策:

プロジェクトをWSL2のLinuxファイルシステム内に移動する: 例えば、/home/youruser/your-projectのようなパスにプロジェクトを完全にコピーし、WSL2ターミナルから操作します。これが最も推奨される方法です。
webpack.watchOptions.pollの有効化（非推奨だが一時的な対応として）: next.config.jsに以下の設定を追加すると、ポーリングによってファイル変更を監視するようになります。ただし、CPU使用率が高くなるため、パフォーマンスへの影響に注意が必要です。
```
// next.config.js
const nextConfig = {
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.watchOptions = {
        poll: 1000, // 1秒ごとにファイル変更をチェック
        aggregateTimeout: 300,
      };
    }
    return config;
  },
};
export default nextConfig;
```
Turbopackがデフォルトの場合、このWebpack設定がどこまで効果があるかは公式ドキュメントで確認が必要になる可能性があります。

3. `next.config.js`の`assetPrefix`設定

assetPrefixを設定している場合、HMRのWebSocket接続先が誤って解釈されることがあります。

回避策:

開発モードではassetPrefixを削除するか、デフォルトの/に設定します。

// next.config.js
const nextConfig = {
  assetPrefix: process.env.NODE_ENV === 'production' ? 'https://yourcdn.com' : '/',
};
export default nextConfig;

4. ルーティングのファイル名とコンポーネント名の大文字小文字不一致

ファイルシステムが大文字小文字を区別しない環境（Windowsなど）で開発し、区別する環境（Linuxサーバーなど）にデプロイする場合に問題となることがあります。HMRもこの影響を受けることがあります。

回避策:

ルーティングを構成するファイル名と、そのファイル内でエクスポートされるコンポーネント名が、大文字小文字を含めて完全に一致していることを確認します。
例: app/dashboard/page.tsx というファイル名であれば、その中のコンポーネントは export default function DashboardPage() { ... } のように一致させます。

5. WebSocket接続エラー（ネットワーク、ブラウザ拡張機能、プロキシ）

ブラウザのコンソールでWebSocket connection to 'ws://localhost:3000/_next/webpack-hmr' failedのようなエラーが表示される場合、クライアント側の問題が考えられます。

回避策:

ネットワーク設定の確認: ファイアウォールやVPNがWebSocket接続をブロックしていないか確認します。一時的に無効にしてテストすることも有効です。
ブラウザ拡張機能の無効化: 一部のブラウザ拡張機能（広告ブロッカー、セキュリティ関連の拡張機能など）がWebSocket接続を妨害することがあります。シークレットモードで試すか、拡張機能を一つずつ無効にして原因を特定します。
プロキシ設定の確認: HTTPプロキシを使用している場合、WebSocket接続が適切にルーティングされているか確認します。

Next.js 16 アップグレードでの破壊的変更と解決策

このセクションでは、Next.js 16へのアップグレードで遭遇する可能性のある、HMR以外の重要な破壊的変更と、それに対する具体的な解決策を解説します。

`middleware.ts`から`proxy.ts`への名称変更

Next.js 16では、ミドルウェアのファイル名と関数名が変更されました。

変更点:

middleware.ts -> proxy.ts
export function middleware(...) -> export function proxy(...)

回避策:
ファイル名を変更し、関数名を修正します。

// proxy.ts (旧 middleware.ts)
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function proxy(request: NextRequest) {
  // プロキシロジック
  // 例: ヘッダーの追加、リダイレクトなど
  return NextResponse.next();
}

非同期になったリクエスト時API

params、searchParams、cookies()、headers()、draftMode()などのリクエスト時APIが非同期になりました。

変更点:
これらのAPIを使用する際にはawaitが必要になります。

回避策:
該当箇所にawaitを追加します。

// app/blog/[slug]/page.tsx
import { PageProps } from 'next';

export default async function Page(props: PageProps<{ slug: string }>) {
  // paramsは非同期になったため await が必要
  const { slug } = await props.params;

  // searchParamsも同様
  // const searchParams = await props.searchParams;

  // cookies()も同様
  // import { cookies } from 'next/headers';
  // const allCookies = await cookies();

  return (
    <div>
      <h1>Blog Post: {slug}</h1>
      {/* ... */}
    </div>
  );
}

`next lint`コマンドの削除

next lintコマンドはNext.js 16で削除されました。

回避策:
CI/CDパイプラインやpre-commitフックでnext lintを使用している場合、直接ESLintまたはBiomeを実行するように変更します。

# .github/workflows/ci.yml の例
# - name: Run Next.js lint
#   run: npm run lint # next lint は削除
- name: Run ESLint
  run: eslint . --ext .js,.jsx,.ts,.tsx

# package.json の scripts も更新
# "lint": "next lint" # 削除または変更
"lint": "eslint . --ext .js,.jsx,.ts,.tsx"

Node.jsおよびTypeScriptの最小バージョン要件の引き上げ

Next.js 16はNode.js 20.9+、TypeScript 5.1+を最小要件とします。

回避策:
package.jsonのenginesフィールドを更新し、開発環境およびCI/CD環境のNode.jsとTypeScriptのバージョンをアップグレードします。

// package.json
{
  "engines": {
    "node": ">=20.9.0"
  },
  "devDependencies": {
    "typescript": "^5.1.0"
  }
}

React 19 アップグレードでの破壊的変更と解決策

このセクションでは、React 19へのアップグレードで特に注意すべき破壊的変更と、それに対する具体的な移行方法を解説します。

`propTypes`の削除とTypeScriptへの移行

React 19ではpropTypesが完全に削除されました。

回避策:

TypeScriptへの移行: propTypesの代替として、TypeScriptを使用することを強く推奨します。これにより、開発段階での型チェックが強化され、ランタイムエラーを減らせます。
react-codemodの利用: react-codemodツールにはprop-types-to-tsのような変換機能がある場合があります。公式ドキュメントを確認し、利用可能なcodemodを試します。

`ReactDOM.render`と`ReactDOM.hydrate`の削除

従来のレガシーなDOMレンダリングAPIが削除されました。

回避策:

ReactDOM.render -> ReactDOM.createRoot().render()
ReactDOM.hydrate -> ReactDOM.hydrateRoot()

// 旧
// import ReactDOM from 'react-dom';
// ReactDOM.render(<App />, document.getElementById('root'));

// 新
import { createRoot } from 'react-dom/client';
const root = createRoot(document.getElementById('root')!);
root.render(<App />);

// Hydrationの場合
// import { hydrateRoot } from 'react-dom/client';
// hydrateRoot(document.getElementById('root')!, <App />);

`forwardRef`の非推奨化と新しいパターン

forwardRefは非推奨となり、refを直接propsとして受け取る新しいパターンが推奨されます。

回避策:
refを直接propsとして受け取るようにコンポーネントを書き換えます。

// 旧
// import React, { forwardRef } from 'react';
// const MyButton = forwardRef((props, ref) => (
//   <button ref={ref} {...props}>
//     {props.children}
//   </button>
// ));

// 新
import React from 'react';

// refを直接propsとして受け取る
interface MyButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  ref?: React.Ref<HTMLButtonElement>; // refの型定義
}

const MyButton: React.FC<MyButtonProps> = ({ ref, ...props }) => (
  <button ref={ref} {...props}>
    {props.children}
  </button>
);

export default MyButton;

新しいJSX Transformの必須化

React 17で導入された新しいJSX TransformがReact 19で必須になりました。

回避策:
ほとんどの現代のプロジェクトでは既に適用されているはずですが、古いBabel設定を使用している場合は、@babel/preset-reactのruntime: 'automatic'オプションが有効になっていることを確認します。

// .babelrc
{
  "presets": [
    ["@babel/preset-react", { "runtime": "automatic" }]
  ]
}

Next.js 16 / React 19 の新機能とベストプラクティス

このセクションでは、Next.js 16とReact 19へのアップグレードがもたらす新しい機能と、それらを最大限に活用するためのベストプラクティスについて解説します。

キャッシュ戦略の明示化と新しいキャッシュAPI

Next.js 16では、use cacheディレクティブとupdateTag()などの新しいAPIにより、キャッシュの制御がより明示的になりました。これにより、Partial Pre-Rendering (PPR) の概念が完成し、パフォーマンスの予測可能性が向上します。（Next.js 公式ドキュメント - Caching, Data Fetching）

ベストプラクティス:

アプリケーションの各部分で、静的にレンダリングすべき部分と動的にレンダリングすべき部分を明確に区別します。
use cacheディレクティブを適切に利用し、キャッシュの粒度と有効期限を最適化します。
データが更新された際には、updateTag()やrevalidateTag()を使用して、関連するキャッシュを無効化し、最新のコンテンツを確実に表示します。

// app/posts/route.ts (API Routeの例)
import { updateTag } from 'next/cache';
import { NextResponse } from 'next/server';

export async function PUT() {
  // 'posts'タグを持つキャッシュを更新
  updateTag('posts');
  return NextResponse.json({ updated: true });
}

Server Componentsの積極的な活用

Next.js 16ではServer Componentsがデフォルトのレンダリングモデルとなり、パフォーマンス向上のために積極的に活用することが推奨されます。

ベストプラクティス:

データフェッチ、データベースアクセス、APIキーなどの機密情報を含むロジックはServer Componentsで実装します。
クライアント側でインタラクティブ性や状態管理を必要としない部分は、すべてServer Componentsとして扱います。
'use client'ディレクティブの使用は最小限に抑え、必要なインタラクティブ性を持つコンポーネントにのみ適用します。

React 19 Actionsによる非同期処理の簡素化

React 19のActionsと新しいHooks (useActionState, useOptimistic, use()) は、フォーム送信やサーバーミューテーションなどの非同期処理を簡素化し、ボイラープレートコードを削減します。（React 19 Release Notes）

ベストプラクティス:

フォーム送信やサーバーとのデータ同期を伴うUIパターンには、useActionStateやuseOptimisticを積極的に採用します。
これにより、手動でのpending状態管理やエラーハンドリングが不要になり、コードの可読性と保守性が向上します。

// Server Actionの例 (app/actions.ts など)
async function updateName(name: string): Promise<string | null> {
  // データベース更新などの非同期処理
  if (name === 'error') {
    return 'Invalid name';
  }
  return null; // 成功時はnull
}

// Client Componentの例
import { useActionState } from 'react';
import { redirect } from 'next/navigation';

function UpdateNameForm({}) {
  // useActionStateで非同期アクションの状態を管理
  const [error, submitAction, isPending] = useActionState(async (previousState, formData) => {
    const name = formData.get('name');
    if (typeof name !== 'string') {
      return 'Name must be a string';
    }
    const error = await updateName(name);
    if (!error) {
      redirect("/profile"); // 成功時にリダイレクト
    }
    return error;
  }, null); // 初期状態はnull

  return (
    <form action={submitAction}>
      <input type="text" name="name" disabled={isPending} />
      <button type="submit" disabled={isPending}>
        {isPending ? 'Updating...' : 'Update'}
      </button>
      {error && <p style={{ color: 'red' }}>{error}</p>}
    </form>
  );
}

まとめと次の一歩

この記事では、Next.js 16とReact 19へのアップグレードで遭遇する可能性のあるHMRの罠、破壊的変更、そして新しい機能の活用方法について網羅的に解説しました。HMRのWebSocket接続問題から、middleware.tsのリネーム、非同期APIの変更、そしてReact 19のpropTypes削除や新しいHooksまで、具体的なコード例を交えながら解決策を示しました。

重要なポイント:

HMR問題: .nextフォルダの削除、WSL2環境でのプロジェクト配置、assetPrefixの確認、ネットワーク設定の見直しが鍵です。
Next.js 16変更: proxy.tsへのリネーム、リクエスト時APIのawait化、next lint削除への対応が必要です。
React 19変更: propTypesからのTypeScript移行、createRootへの変更、forwardRefの新しいパターンへの移行が求められます。
新機能活用: キャッシュコンポーネント、Server Components、React Actionsを積極的に利用し、パフォーマンスと開発体験を向上させましょう。

次の一歩:
アップグレード作業は慎重に行う必要があります。まずは既存のテストスイートが完全にパスすることを確認し、段階的なアップグレード（例: React 18.3への先行アップグレードと警告解消）を検討してください。そして、必ずNext.js 公式ドキュメントとReact 公式ドキュメントの最新のアップグレードガイドを参照し、詳細な変更点と推奨事項を確認してください。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

Next.js 16/React 19アップグレードで遭遇！HMRの罠と解決策

Next.js 16 / React 19 アップグレードの前提と環境

次世代のWeb開発を担うNext.js 16とReact 19

必須の最小要件とアップグレードコマンド

HMRの罠：WebSocket接続とトラブルシューティング

Next.js 16におけるHMRの変更点

HMRが機能しない場合の一般的な原因と回避策

1. .nextフォルダやnode_modulesの破損

2. WSL2環境特有のファイルシステム監視問題

3. next.config.jsのassetPrefix設定

4. ルーティングのファイル名とコンポーネント名の大文字小文字不一致

5. WebSocket接続エラー（ネットワーク、ブラウザ拡張機能、プロキシ）

Next.js 16 アップグレードでの破壊的変更と解決策

middleware.tsからproxy.tsへの名称変更

非同期になったリクエスト時API

next lintコマンドの削除

Node.jsおよびTypeScriptの最小バージョン要件の引き上げ

React 19 アップグレードでの破壊的変更と解決策

propTypesの削除とTypeScriptへの移行

ReactDOM.renderとReactDOM.hydrateの削除

forwardRefの非推奨化と新しいパターン

新しいJSX Transformの必須化

Next.js 16 / React 19 の新機能とベストプラクティス

キャッシュ戦略の明示化と新しいキャッシュAPI

Server Componentsの積極的な活用

React 19 Actionsによる非同期処理の簡素化

まとめと次の一歩

1. `.next`フォルダや`node_modules`の破損

3. `next.config.js`の`assetPrefix`設定

`middleware.ts`から`proxy.ts`への名称変更

`next lint`コマンドの削除

`propTypes`の削除とTypeScriptへの移行

`ReactDOM.render`と`ReactDOM.hydrate`の削除

`forwardRef`の非推奨化と新しいパターン