メインコンテンツまでスキップ

エラーハンドリング

エラーは2つのカテゴリに分けられます：予期されたエラーとキャッチされない例外です：

  • 予期されたエラーを戻り値としてモデル化する：Server Actionsで予期されたエラーにtry/catchを使用するのは避けます。これらのエラーを管理し、クライアントに返すためにuseActionStateを使用します。
  • 予期しないエラーにはエラーバウンダリを使用する：error.tsxとglobal-error.tsxファイルを使用してエラーバウンダリを実装し、予期しないエラーを処理し、フォールバックUIを提供します。

予期されたエラーの処理​

予期されたエラーは、アプリケーションの通常の操作中に発生する可能性のあるエラーであり、サーバーサイドのフォームバリデーションや失敗したリクエストからのエラーなどです。これらのエラーは明示的に処理され、クライアントに返されるべきです。

Server Actionsからの予期されたエラーの処理​

useActionStateフックを使用して、Server Actionsの状態を管理し、エラーを処理します。このアプローチは、予期されたエラーに対してtry/catchブロックを避け、例外としてスローするのではなく、戻り値としてモデル化するべきです。

app/actions.ts
'use server'

import { redirect } from 'next/navigation'

export async function createUser(prevState: any, formData: FormData) {
  const res = await fetch('https://...')
  const json = await res.json()

  if (!res.ok) {
    return { message: '有効なメールアドレスを入力してください' }
  }

  redirect('/dashboard')
}

その後、アクションをuseActionStateフックに渡し、返されたstateを使用してエラーメッセージを表示できます。

app/ui/signup.tsx
'use client'

import { useActionState } from 'react'
import { createUser } from '@/app/actions'

const initialState = {
  message: '',
}

export function Signup() {
  const [state, formAction, pending] = useActionState(createUser, initialState)

  return (
    <form action={formAction}>
      <label htmlFor="email">Email</label>
      <input type="text" id="email" name="email" required />
      {/* ... */}
      <p aria-live="polite">{state?.message}</p>
      <button disabled={pending}>Sign up</button>
    </form>
  )
}

クライアントコンポーネントからトーストメッセージを表示するために、返された状態を使用することもできます。

Server Componentsからの予期されたエラーの処理​

Server Component内でデータを取得する際、レスポンスを使用してエラーメッセージを条件付きでレンダリングしたり、redirectを使用することができます。

app/page.tsx
export default async function Page() {
  const res = await fetch(`https://...`)
  const data = await res.json()

  if (!res.ok) {
    return 'エラーが発生しました。'
  }

  return '...'
}

キャッチされない例外​

キャッチされない例外は、アプリケーションの通常のフロー中に発生すべきでないバグや問題を示す予期しないエラーです。これらはエラーをスローすることで処理され、その後エラーバウンダリによってキャッチされます。

  • 一般的な方法：root レイアウト以下のキャッチされないエラーをerror.jsで処理します。
  • オプション：ネストされたerror.jsファイル（例：app/dashboard/error.js）を使用して、詳細なキャッチされないエラーを処理します。
  • 非一般的な方法：root レイアウトでキャッチされないエラーをglobal-error.jsで処理します。

エラーバウンダリの使用​

Next.jsはキャッチされない例外を処理するためにエラーバウンダリを使用します。エラーバウンダリは子コンポーネント内のエラーをキャッチし、クラッシュしたコンポーネントツリーの代わりにフォールバックUIを表示します。

ルートセグメント内にerror.tsxファイルを追加し、Reactコンポーネントをエクスポートすることでエラーバウンダリを作成します：

app/dashboard/error.tsx
'use client' // エラーバウンダリはClient Componentsでなければなりません

import { useEffect } from 'react'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // エラーをエラーレポートサービスにログします
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>何かがうまくいきませんでした！</h2>
      <button
        onClick={
          // セグメントを再レンダリングして回復を試みます
          () => reset()
        }
      >
        もう一度試す
      </button>
    </div>
  )
}

エラーを親のエラーバウンダリにバブルアップさせたい場合は、errorコンポーネントをレンダリングする際にthrowすることができます。

ネストされたルートでのエラー処理​

エラーは最も近い親のエラーバウンダリにバブルアップします。これにより、ルート階層の異なるレベルにerror.tsxファイルを配置することで、詳細なエラーハンドリングが可能になります。

ネストされたエラーコンポーネントの階層ネストされたエラーコンポーネントの階層

グローバルエラーの処理​

あまり一般的ではありませんが、国際化を活用している場合でも、root レイアウトでエラーを処理するために、root appディレクトリにあるapp/global-error.jsを使用できます。グローバルエラーUIは、アクティブなときにroot レイアウトまたはテンプレートを置き換えるため、独自の<html>および<body>タグを定義する必要があります。

app/global-error.tsx
'use client' // エラーバウンダリはClient Componentsでなければなりません

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    // global-errorはhtmlとbodyタグを含める必要があります
    <html>
      <body>
        <h2>何かがうまくいきませんでした！</h2>
        <button onClick={() => reset()}>もう一度試す</button>
      </body>
    </html>
  )
}