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:エラー時に表示する UIonError:エラーを捕まえたときの処理(ログ送信)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("意図的なエラー(動作確認用)");
}
確認したいエラーバウンダリの内側に一時的に置き、次の点を確認します。
- fallback が想定した範囲だけに表示される
- 「再試行」で復帰できる
- 別ページへの遷移でエラー表示が解除される
- ログ送信処理が呼ばれる
開発環境では、開発ツールのエラーオーバーレイが 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つを置くだけでも、障害がユーザーに与える影響をかなり小さくできます。
