はじめに：Nuxtのエラー管理をもっとスマートに

Nuxtアプリケーションを開発していると、エラー処理は避けて通れない重要な課題です。特にサーバーサイドレンダリング（SSR）とクライアントサイドレンダリング（CSR）が混在する環境では、エラーの検知や表示を一貫して行うことが難しくなります。そんな中、Nuxtが提供するuseError composableは、グローバルなエラーステートをリアクティブに管理し、SSRとCSRの両方でシームレスにエラー情報を扱える強力なツールです。

この記事では、useErrorの基本的な使い方だけでなく、実務での具体的なユースケースや注意すべきポイントを丁寧に解説します。これにより、Nuxtのエラー管理をより堅牢かつ効率的に実装できるようになります。

まず結論：useErrorのポイントまとめ

• グローバルなNuxtエラーをリアクティブに取得できる
  SSR・CSR両方で動作し、エラー状態の変化を自動で追跡可能。

• パラメータ不要で簡単に利用可能
  const error = useError()だけで現在のエラー情報を取得できる。

• エラーオブジェクトはRefで返される
  error.valueでアクセスし、リアクティブに監視できる。

• コンポーネントやプラグイン、ページ内で利用可能
  エラー状態に応じたUI制御やログ出力に活用できる。

• SSR時のエラー伝播やCSRでの再レンダリングに強い
  Nuxtの内部エラーハンドリングと連携し、安定した動作を実現。

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

使うべきケース

• グローバルなエラー状態を監視したいとき
  ページ全体やアプリケーション単位で発生したエラーを一元管理したい場合に最適です。

• SSRとCSRの両方でエラーを扱う必要があるとき
  サーバーで発生したエラーをクライアントに反映させたい場合に有効です。

• エラーに応じて動的にUIを切り替えたいとき
  エラーメッセージの表示やリトライボタンの表示制御などに活用できます。

• プラグインやミドルウェアでエラーを検知し処理したいとき
  アプリ全体のエラーハンドリングロジックに組み込むことが可能です。

使わない方がよいケース

• 局所的なエラー処理だけで完結する場合
  例えば、単一のフォームバリデーションエラーなど、グローバル状態を必要としない場合は、ローカルな状態管理で十分です。

• 外部APIのエラーを個別に管理したい場合
  APIごとに異なるエラー処理が必要な場合は、useErrorよりも専用のエラーステート管理を検討してください。

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

1. ページ全体のエラー表示

サーバーやクライアントで発生したエラーをページのトップでキャッチし、ユーザーにわかりやすく通知します。

<script setup lang="ts">
const error = useError()
</script>

<template>
  <div>
    <div v-if="error">
      <p>エラーが発生しました: {{ error.statusMessage || error.message }}</p>
    </div>
    <nuxt-page v-else />
  </div>
</template>

2. プラグイン内でのエラー監視とログ出力

プラグインでuseErrorを使い、エラー発生時に外部ログサービスへ送信する例です。

export default defineNuxtPlugin(() => {
  const error = useError()

  watch(error, (newError) => {
    if (newError) {
      // 例: 外部ログサービスに送信
      console.error('Nuxt global error:', newError)
    }
  })
})

3. エラーに応じたリトライUIの表示

API通信エラー時にリトライボタンを表示し、ユーザーが再試行できるようにします。

<script setup lang="ts">
const error = useError()

function retry() {
  // 再試行ロジック
}
</script>

<template>
  <div>
    <div v-if="error">
      <p>通信エラーが発生しました。再試行してください。</p>
      <button @click="retry">再試行</button>
    </div>
    <nuxt-page v-else />
  </div>
</template>

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

SSRとCSRのエラー同期に注意

useErrorはSSR時に発生したエラーをCSRに引き継ぎますが、Hydration時にエラー状態が変わるとUIの不整合が起きることがあります。エラー状態の変化は慎重に扱い、必要に応じてエラーリセットや状態管理を工夫しましょう。

パフォーマンスへの影響

リアクティブなエラーステートは便利ですが、頻繁に変化する場合は不要な再レンダリングを招くことがあります。エラー監視は必要最低限に留め、UIの更新範囲を限定することが望ましいです。

エラーオブジェクトの内容を過信しすぎない

useErrorが返すエラーオブジェクトはNuxt内部のエラー情報を含みますが、外部APIの詳細なエラー情報やカスタムエラーは含まれない場合があります。必要に応じて独自のエラー管理も併用してください。

まとめ

NuxtのuseErrorは、グローバルなエラーステートをリアクティブに管理し、SSRとCSRの両方で安定したエラー処理を実現する強力なツールです。実務ではページ全体のエラー表示やプラグインでのログ送信、ユーザー向けのリトライUIなど多様な場面で活用できます。一方で、Hydration時の状態同期やパフォーマンス面の注意も必要です。これらを理解し適切に使いこなすことで、Nuxtアプリの信頼性とユーザー体験を大きく向上させることができます。