React のエラーバウンダリ設計入門:画面全体を真っ白にしないための考え方と実装

React アプリを運用していると、「画面が真っ白になった」という報告を受けることがあります。原因の多くは、描画中に起きたエラーをどこでも受け止めていないことです。

この記事では、React の エラーバウンダリ(Error Boundary) について、仕組み・実装・置き場所の設計・確認方法までを入門者向けに解説します。

この記事でわかること

  • エラーバウンダリが捕まえるエラーと捕まえないエラー
  • クラスコンポーネントによる最小実装
  • react-error-boundary を使った実用的な書き方
  • アプリ全体・ページ・部品の3層で考える置き場所の設計
  • イベントハンドラや非同期処理のエラーの扱い方
  • React 19 で追加されたエラー通知オプション
  • 動作確認とテストの方法

前提環境

  • React 18 / 19
  • TypeScript
  • react-error-boundary(v4 系以降を想定)
  • ルーティングの例では React Router を使用

なぜ画面全体が消えるのか

React は 16 以降、描画中のエラーがどこでも受け止められなかった場合に、ルート配下のコンポーネントツリーをすべてアンマウントします。

壊れた状態の UI を表示し続けると、誤った情報を表示したり、誤った操作をさせたりする危険があります。それを避けるための設計です。ただ、ユーザーから見るとヘッダーもメニューも消え、何もできなくなります。

たとえば次のコードは、API のレスポンスに profile がないだけで TypeError になり、画面全体が消えます。

type User = { profile?: { name: string } };

function UserName({ user }: { user: User }) {
  return <span>{user.profile!.name}</span>;
}

エラーバウンダリが捕まえる範囲

エラーバウンダリは、自分より下のツリーで起きた次のエラーを捕まえます。

  • 描画(レンダリング)中のエラー
  • ライフサイクルメソッド内のエラー
  • コンストラクタ内のエラー

一方、次のエラーは捕まえません。

捕まえないもの 例
イベントハンドラ onClick 内で throw
非同期処理 setTimeout、Promise、async 関数内
サーバーサイドレンダリング SSR 中のエラー
エラーバウンダリ自身 fallback の描画中のエラーなど

イベントハンドラのエラーは描画を壊さないので、画面は消えません。その代わりエラーは黙って起き、ユーザーには何も伝わりません。これは別の方法で扱う必要があります(後述)。

最小実装:クラスコンポーネント

エラーバウンダリに必要なメソッドには、対応するフックがありません。そのため、自分で書く場合はクラスコンポーネントになります。

import { Component, type ErrorInfo, type ReactNode } from "react";

type Props = {
  fallback: ReactNode;
  children: ReactNode;
  onError?: (error: unknown, info: ErrorInfo) => void;
};
type State = { hasError: boolean };

export class ErrorBoundary extends Component<Props, State> {
  state: State = { hasError: false };

  static getDerivedStateFromError(): State {
    return { hasError: true };
  }

  componentDidCatch(error: unknown, info: ErrorInfo) {
    this.props.onError?.(error, info);
  }

  render() {
    return this.state.hasError ? this.props.fallback : this.props.children;
  }
}

2つのメソッドの役割は次のとおりです。

  • getDerivedStateFromError:描画の段階で呼ばれ、fallback を表示するための state を返します。ここには副作用を書きません。
  • componentDidCatch:画面への反映が終わった段階で呼ばれます。ログ送信などの副作用はこちらに書きます。info.componentStack から、どのコンポーネントで起きたかを追えます。

ただし、この実装には一度エラーになると元に戻る方法がないという弱点があります。

実務向け:react-error-boundary

再試行や自動リセットを自分で作るのは手間がかかるので、実務では react-error-boundary を使うのが一般的です。

npm install react-error-boundary
import { ErrorBoundary, type FallbackProps } from "react-error-boundary";

function ErrorFallback({ error, resetErrorBoundary }: FallbackProps) {
  const message = error instanceof Error ? error.message : String(error);
  return (
    <div role="alert">
      <p>表示中に問題が発生しました。</p>
      {import.meta.env.DEV && <pre>{message}</pre>}
      <button onClick={resetErrorBoundary}>再試行</button>
    </div>
  );
}

export function UserCard({ user }: { user: User }) {
  return (
    <ErrorBoundary
      FallbackComponent={ErrorFallback}
      onError={(error, info) => reportError(error, info.componentStack)}
    >
      <UserName user={user} />
    </ErrorBoundary>
  );
}

※ reportError は説明用の仮の関数です。監視サービスを使う場合は、その SDK の API に置き換えてください。

主な props は次のとおりです。

  • FallbackComponent / fallbackRender / fallback:エラー時に表示する UI
  • onError:エラーを捕まえたときの処理(ログ送信)
  • onReset:リセット時の後始末(state やキャッシュを戻す)
  • resetKeys:配列の値が変わると自動でリセット

置き場所の設計:3層で考える

エラーバウンダリの設計で一番大切なのは、「どこまでを一緒に壊すか」を決めることです。次の3層で考えると整理しやすくなります。

App
├─ [L1] アプリ全体   … 最後の砦。全画面エラー
│   ├─ Header / Nav
│   └─ [L2] ページ単位 … ページの中身だけ差し替え
│       ├─ [L3] 部品単位 … カード1枚だけ差し替え
│       └─ [L3] 部品単位

L1:アプリ全体

<ErrorBoundary FallbackComponent={FullPageError}>
  <App />
</ErrorBoundary>

ほかのどこにも捕まらなかったエラーの受け皿です。ここにエラーが頻繁に届く場合は、下の層の配置が足りていません。

L2:ページ単位

import { Outlet, useLocation } from "react-router-dom";

function Layout() {
  const { pathname } = useLocation();
  return (
    <>
      <Header />
      <ErrorBoundary FallbackComponent={PageError} resetKeys={[pathname]}>
        <Outlet />
      </ErrorBoundary>
    </>
  );
}

ヘッダーやメニューを残したまま、ページの中身だけをエラー表示にできます。resetKeys にパスを渡すと、別のページへ移動したときに自動でエラー表示が解除されます。これを入れないと、どのページに移動してもエラー表示が残ります。

L3:部品単位

<div className="dashboard">
  <ErrorBoundary fallback={<CardError title="売上推移" />}>
    <SalesChart />
  </ErrorBoundary>
  <ErrorBoundary fallback={<CardError title="お知らせ" />}>
    <Notices />
  </ErrorBoundary>
</div>

ダッシュボードのカードやグラフなど、壊れても他の機能に影響しない部品を個別に包みます。

包みすぎに注意

細かく包みすぎると、「フォームの一部だけエラー表示なのに送信ボタンは押せる」といった危険な状態が生まれます。ユーザーにとって意味のある単位で区切ることが基本です。

イベントハンドラ・非同期処理のエラー

エラーバウンダリまで届かないエラーは、次の2つの方針で扱います。

ユーザーが対処できるエラーは、その場で伝える

const [saveError, setSaveError] = useState<string | null>(null);

const handleSave = async () => {
  try {
    await save(form);
  } catch {
    setSaveError("保存に失敗しました。時間をおいて再度お試しください。");
  }
};

想定外のエラーはエラーバウンダリへ渡す

import { useErrorBoundary } from "react-error-boundary";

function DeleteButton({ id }: { id: string }) {
  const { showBoundary } = useErrorBoundary();

  const handleClick = async () => {
    try {
      await deleteItem(id);
    } catch (error) {
      showBoundary(error);
    }
  };

  return <button onClick={handleClick}>削除</button>;
}

showBoundary を呼ぶと、最も近いエラーバウンダリの fallback に切り替わります。続行すると危険なエラーの見せ方を1か所にまとめられます。

データ取得ライブラリには、取得エラーを描画時に throw させてエラーバウンダリに渡す設定があるものもあります(例:TanStack Query の throwOnError)。その場合は onReset でキャッシュもリセットしないと、再試行してもすぐに同じエラーになります。詳しくは各ライブラリの公式ドキュメントを確認してください。

React 19 のエラー通知オプション

React 19 では、createRoot にエラー通知用のコールバックを渡せるようになりました。

import { createRoot } from "react-dom/client";

createRoot(document.getElementById("root")!, {
  onUncaughtError: (error, errorInfo) => {
    reportError(error, errorInfo.componentStack);
  },
  onCaughtError: (error, errorInfo) => {
    reportError(error, errorInfo.componentStack);
  },
}).render(<App />);
  • onUncaughtError:どのエラーバウンダリにも捕まらなかったエラー
  • onCaughtError:エラーバウンダリが捕まえたエラー

ログ送信を1か所に集約できるのが利点です。React 18 では使えないので、各バウンダリの onError で送信してください。

動作確認の方法

わざとエラーを起こす

function Bomb(): never {
  throw new Error("意図的なエラー(動作確認用)");
}

確認したいエラーバウンダリの内側に一時的に置き、次の点を確認します。

  1. fallback が想定した範囲だけに表示される
  2. 「再試行」で復帰できる
  3. 別ページへの遷移でエラー表示が解除される
  4. ログ送信処理が呼ばれる

開発環境では、開発ツールのエラーオーバーレイが fallback の上に重なることがあります。本番ビルドでも一度確認しておくと確実です。

自動テスト

import { render, screen } from "@testing-library/react";
import { vi, test, expect } from "vitest";

test("子でエラーが起きたら fallback を表示する", () => {
  const spy = vi.spyOn(console, "error").mockImplementation(() => {});

  render(
    <ErrorBoundary fallback={<p>エラーが発生しました</p>}>
      <Bomb />
    </ErrorBoundary>
  );

  expect(screen.getByText("エラーが発生しました")).toBeInTheDocument();
  spy.mockRestore();
});

React はエラーを console.error に出力するため、テスト中だけ抑制しています。

注意点

  • fallback を壊さない:fallback で起きたエラーは同じバウンダリでは捕まりません。外部データに依存させず、シンプルに保ちます。
  • 本番でエラー詳細を出さない:エラーメッセージやスタックには内部情報が含まれることがあります。
  • Error 以外も throw される:instanceof Error で判定してから扱います。
  • リセット時に原因を取り除く:onReset で state やキャッシュを戻します。
  • フレームワークの流儀に従う:Next.js などは独自のエラー処理の仕組みを持っています。

まとめ

  • エラーバウンダリは、描画中のエラーで画面全体が消えるのを防ぐ仕組み
  • イベントハンドラ・非同期処理・SSR のエラーは対象外。その場で処理するか、showBoundary で渡す
  • 置き場所は「アプリ全体/ページ/部品」の3層で考える
  • react-error-boundary の resetKeys と onReset で、必ず復帰できるようにする
  • ログは onError、React 19 なら onCaughtError / onUncaughtError に集約する

最初はアプリ全体とページ単位の2つを置くだけでも、障害がユーザーに与える影響をかなり小さくできます。

\ 最新情報をチェック /

コメントを残す

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください。