エラーハンドリング
エラーは2つのカテゴリに分けることができます:予期されたエラー と 未キャッチ例外:
- 予期されたエラーを戻り値としてモデル化する:Server Actionsで予期されたエラーには
try
/catch
を使用しないでください。これらのエラーを管理し、クライアントに返すにはuseFormState
を使います。 - 予期しないエラーにはエラーボーダリを使用する:予期しないエラーを処理し、フォールバックUIを提供するには、
error.tsx
およびglobal-error.tsx
ファイルを使用してエラーボーダリを実装します。
予期されたエラーの処理
予期されたエラーとは、サーバー側フォームバリデーションやリクエストの失敗など、アプリケーションの通常の操作中に発生する可能性があるエラーです。これらのエラーは明示的に処理し、クライアントに返すべきです。
Server Actionsからの予期されたエラーを処理する
useFormState
フックを使用して、Server Actionsの状態を管理し、エラーを処理します。このアプローチはtry
/catch
ブロックを避け、予期されたエラーを例外としてスローするのではなく、戻り値としてモデル化します。
- TypeScript
- JavaScript
'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')
}
'use server'
import { redirect } from 'next/navigation'
export async function createUser(prevState, formData) {
const res = await fetch('https://...')
const json = await res.json()
if (!res.ok) {
return { message: '正しいメールアドレスを入力してください' }
}
redirect('/dashboard')
}
その後、useFormState
フックにアクションを渡し、返されるstate
を使用してエラーメッセージを表示できます。
- TypeScript
- JavaScript
'use client'
import { useFormState } from 'react-dom'
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>
)
}
'use client'
import { useFormState } from 'react-dom'
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>
)
}
Good to know: これらの例は、Next.js App Routerと一緒にバンドルされているReactの
useFormState
フックを使用しています。React 19を使用している場合は、useActionState
を代わりに使用してください。詳細についてはReactドキュメントを参照してください。
返された状態を使用して、クライアントコンポーネントからトーストメッセージを表示することもできます。
Server Componentsからの予期されたエラーを処理する
Server Component内でデータを取得する際には、応答を利用してエラーメッセージを条件付けてレンダリングするか、redirect
を使用してください。
- TypeScript
- JavaScript
export default async function Page() {
const res = await fetch(`https://...`)
const data = await res.json()
if (!res.ok) {
return 'エラーが発生しました。'
}
return '...'
}
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コンポーネントをエクスポートすることでエラーボーダリを作成します:
- TypeScript
- JavaScript
'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()
}
>
Try again
</button>
</div>
)
}
'use client' // エラーボーダリはClient Componentsである必要があります
import { useEffect } from 'react'
export default function Error({ error, reset }) {
useEffect(() => {
// エラーをエラーレポートサービスにログします
console.error(error)
}, [error])
return (
<div>
<h2>何かがうまくいきませんでした!</h2>
<button
onClick={
// セグメントを再レンダリングすることで回復を試みます
() => reset()
}
>
Try again
</button>
</div>
)
}
エラーを親エラーボーダリまで伝播させたい場合は、error
コンポーネントのレンダリング時にthrow
することができます。
ネストされたルートでのエラー処理
エラーは最も近い親エラーボーダリに伝播します。これにより、ルート階層の異なるレベルにerror.tsx
ファイルを配置することで詳細なエラーハンドリングが可能になります。
グローバルエラーの処理
あまり一般的ではありませんが、国際化を活用していても、root レイアウト内でapp/global-error.js
を使用してエラーを処理できます。グローバルエラーUIは、アクティブになったときにroot レイアウトまたはテンプレートを置き換えるため、自身の<html>
および<body>
タグを定義する必要があります。
- TypeScript
- JavaScript
'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()}>Try again</button>
</body>
</html>
)
}
'use client' // エラーボーダリはClient Componentsである必要があります
export default function GlobalError({ error, reset }) {
return (
// global-errorにはhtmlとbodyタグが含まれていなければなりません
<html>
<body>
<h2>何かがうまくいきませんでした!</h2>
<button onClick={() => reset()}>Try again</button>
</body>
</html>
)
}