エラーハンドリング

エラーは、**予期されるエラー**と**キャッチされない例外**の 2 つのカテゴリに分類できます。

**予期されるエラーを戻り値としてモデル化する**: サーバーアクションで予期されるエラーに対して try/catch を使用することは避けてください。これらのエラーを管理し、クライアントに返すには、useFormState を使用してください。
**予期しないエラーにはエラー境界を使用する**: 予期しないエラーを処理し、フォールバック UI を提供するには、error.tsx および global-error.tsx ファイルを使用してエラー境界を実装します。

予期されるエラーの処理

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

サーバーアクションからの予期されるエラーの処理

エラー処理を含め、サーバーアクションの状態を管理するには、useFormState フックを使用します。このアプローチでは、スローされた例外ではなく、戻り値としてモデル化する必要がある予期されるエラーに対する 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: 'Please enter a valid email' }
  }
 
  redirect('/dashboard')
}

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

app/ui/signup.tsx

'use client'
 
import { useFormState } from 'react'
import { createUser } from '@/app/actions'
 
const initialState = {
  message: '',
}
 
export function Signup() {
  const [state, formAction] = useFormState(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>Sign up</button>
    </form>
  )
}

**知っておくとよいこと**: これらの例では、Next.js App Router にバンドルされている React の useFormState フックを使用しています。React 19 を使用している場合は、代わりに useActionState を使用してください。詳細については、React ドキュメントを参照してください。

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

サーバーコンポーネントからの予期されるエラーの処理

サーバーコンポーネント内でデータをフェッチするときは、応答を使用して、エラーメッセージを条件付きでレンダリングしたり、redirectしたりできます。

app/page.tsx

export default async function Page() {
  const res = await fetch(`https://...`)
  const data = await res.json()
 
  if (!res.ok) {
    return 'There was an error.'
  }
 
  return '...'
}

キャッチされない例外

捕捉されなかった例外は、アプリケーションの通常の流れの中で発生すべきではないバグや問題を示す予期しないエラーです。これらはエラーをスローすることで処理される必要があり、そのエラーはエラー境界によって捕捉されます。

一般的: ルートレイアウトより下の階層で捕捉されなかったエラーをerror.jsで処理します。
任意: ネストされたerror.jsファイル（例：app/dashboard/error.js）を使用して、より細かく捕捉されなかったエラーを処理します。
一般的ではない: ルートレイアウトで捕捉されなかったエラーをglobal-error.jsで処理します。

エラー境界の使用

Next.jsは、エラー境界を使用して捕捉されなかった例外を処理します。エラー境界は、子コンポーネントのエラーを捕捉し、クラッシュしたコンポーネントツリーの代わりにフォールバックUIを表示します。

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

app/dashboard/error.tsx

'use client' // Error boundaries must be Client Components
 
import { useEffect } from 'react'
 
export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // Log the error to an error reporting service
    console.error(error)
  }, [error])
 
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button
        onClick={
          // Attempt to recover by trying to re-render the segment
          () => reset()
        }
      >
        Try again
      </button>
    </div>
  )
}

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

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

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

グローバルエラーの処理

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

app/global-error.tsx

'use client' // Error boundaries must be Client Components
 
export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    // global-error must include html and body tags
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}