NuxtのcreateError関数を活用するための実践ガイド

Nuxtでのエラーハンドリングは、ユーザー体験の向上や開発効率の改善に直結します。特にcreateError関数は、エラーオブジェクトに追加情報を持たせてスローできるため、サーバーサイド・クライアントサイド双方で柔軟なエラー処理を実現します。本記事では、createErrorの使い方を深掘りし、実務での活用例や注意点を交えて解説します。

1. イントロ：なぜcreateErrorが便利なのか？

通常のJavaScriptのErrorオブジェクトはメッセージとスタックトレースを持ちますが、HTTPステータスコードやカスタムデータを含めることはできません。NuxtのcreateErrorはこれを拡張し、例えばAPIのレスポンスに適切なステータスコードを付与したり、フロントエンドでのエラー表示を制御したりできます。

これにより、

• APIレスポンスの一貫性が保てる
• エラーの種類に応じた適切なUI表示が可能になる
• サーバーとクライアントで同じエラーオブジェクトを共有できる

といったメリットがあります。

2. まず結論：createErrorの要点まとめ

• createErrorは文字列またはオブジェクトを引数に取り、拡張されたエラーオブジェクトを生成する
• オブジェクトにはstatusCodeやstatusMessage、fatalなどのプロパティを指定可能
• サーバーサイドではフルスクリーンのエラーページ表示、クライアントサイドでは非致命的エラーとして扱われる
• APIルートでのエラーハンドリングに最適で、クライアントに適切なステータス情報を返せる
• ユーザー入力を直接エラーメッセージに含めるのはセキュリティリスクになるため注意が必要

3. いつ使うべきか？使わない方がよいケース

使うべきケース

• APIレスポンスでHTTPステータスコードを明示的に返したいとき
• ページやコンポーネントのデータ取得時にエラーを検知し、Nuxtのエラーページを表示したいとき
• サーバーとクライアントで共通のエラー処理ロジックを実装したいとき
• エラーに追加情報（例：fatalフラグやカスタムデータ）を持たせて処理を分岐したいとき

使わない方がよいケース

• 単純なJavaScriptの例外処理で十分な場合（例：ローカルな計算エラーなど）
• ユーザー入力をそのままエラーメッセージに含めてしまう可能性がある場合（XSSや情報漏洩リスク）
• エラーの詳細をクライアントに公開したくない場合（内部エラーの詳細はログに留めるべき）

4. 実務でよくあるユースケースとサンプルコード

ユースケース1：ページのデータ取得で404エラーを返す

APIからデータが取得できなかった場合に、404ステータスを返してエラーページを表示します。

const route = useRoute()
const { data } = await useFetch(`/api/items/${route.params.id}`)
if (!data.value) {
  throw createError({ statusCode: 404, statusMessage: 'Item Not Found' })
}

ユースケース2：APIルートでのエラーハンドリング

APIの処理中に条件に合わない場合、適切なステータスコードとメッセージを返します。

export default eventHandler(() => {
  const user = getUserFromRequest()
  if (!user) {
    throw createError({
      statusCode: 401,
      statusMessage: 'Unauthorized'
    })
  }
  // 処理続行
})

ユースケース3：致命的なエラーをクライアントで表示

クライアント側でフルスクリーンのエラーページを表示したい場合はfatal: trueを設定します。

try {
  const { data } = await useFetch('/api/critical-data')
  if (!data.value) {
    throw createError({ statusCode: 500, fatal: true, statusMessage: 'Critical Error' })
  }
} catch (error) {
  // ここでエラーをキャッチしても、fatal:trueならフルスクリーンエラーが表示される
}

5. よくある落とし穴・注意点

SSRとCSRでの挙動の違い

• サーバーサイドでcreateErrorをスローすると、Nuxtは自動的にエラーページをレンダリングします。
• クライアントサイドでは、fatalがtrueでない限り非致命的なエラーとして扱われ、画面遷移を止めない場合があります。

Hydrationエラーに注意

サーバーでエラーが発生しエラーページが返された場合、クライアント側でのHydration時に状態が合わずエラーになることがあります。エラー状態の管理は慎重に行いましょう。

パフォーマンスへの影響

過剰に細かいエラー処理や大量のエラーオブジェクト生成はパフォーマンスに影響する可能性があります。必要な情報だけを付与し、無駄な処理は避けましょう。

セキュリティ面の注意

• ユーザーからの入力を直接messageやstatusMessageに含めない
• 内部のスタックトレースや詳細情報はクライアントに公開しない
• APIレスポンスのエラーメッセージは簡潔かつ安全な内容にする

6. まとめ

NuxtのcreateErrorは、サーバー・クライアント双方で統一的かつ柔軟なエラーハンドリングを実現する強力なツールです。HTTPステータスコードやカスタム情報を持たせることで、ユーザー体験の向上や開発効率の改善に寄与します。一方で、使いどころやセキュリティ面の配慮も重要です。本記事のポイントを押さえ、実務での適切な活用を目指しましょう。