Nuxtのルートミドルウェアとは？〜何が嬉しいのか〜

Nuxtのルートミドルウェアは、ページ遷移時に処理を挟み込むことで、認証チェックやリダイレクト、エラーハンドリングなどを柔軟に実装できる仕組みです。これにより、アプリケーションのルーティング制御を一元管理でき、ユーザー体験の向上やセキュリティ強化が期待できます。

例えば、ログインしていないユーザーをログインページにリダイレクトしたり、特定の条件でカスタムエラーページを表示したりといった処理を簡潔に実装可能です。これまで個別のページコンポーネントで行っていた認証判定や遷移制御をミドルウェアに集約することで、コードの重複を減らし保守性を高められます。

まず結論：ルートミドルウェアのポイント

• ルート遷移時に実行される関数を定義し、遷移の制御や副作用を実装できる
• defineNuxtRouteMiddleware で名前付きミドルウェアを簡単に作成可能
• to（遷移先）と from（遷移元）のルート情報を受け取り、条件に応じてリダイレクトやエラーを発生させられる
• 認証チェックやアクセス制限、カスタムエラーページ表示などに最適
• navigateTo や abortNavigation といったヘルパー関数も利用できる

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

使うべきケース

• 認証・認可の制御
  ユーザーのログイン状態や権限に応じてアクセス可能なページを制限したい場合。
• 共通のルーティングロジックの集約
  複数ページで共通する遷移制御（例：特定条件でのリダイレクト）を一箇所にまとめたい場合。
• エラーハンドリングのカスタマイズ
  ルート遷移時に特定の条件でエラーをスローし、カスタムエラーページを表示したい場合。

使わない方がよいケース

• ページ固有のUIロジックや状態管理
  ミドルウェアはあくまでルーティング制御のための仕組みなので、UIの状態管理やコンポーネント固有の処理はページやコンポーネント内で行うべきです。
• 非同期データフェッチのためだけの利用
  データ取得は asyncData や useFetch などのNuxtのデータフェッチ機構を使う方が適切です。
• 複雑すぎるロジック
  ミドルウェアはシンプルな条件分岐やリダイレクトに向いています。複雑なビジネスロジックは別のサービス層やストアで管理しましょう。

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

1. 認証チェックによるアクセス制限

ログインしていないユーザーをログインページにリダイレクトする例です。

export default defineNuxtRouteMiddleware((to) => {
  const auth = useState('auth')

  if (!auth.value.isAuthenticated && to.path !== '/login') {
    return navigateTo('/login')
  }
})

このミドルウェアを middleware/auth.ts に保存し、nuxt.config.ts でグローバルに適用するか、ページごとに指定します。

2. 管理者専用ページへのアクセス制御

ユーザーの権限をチェックし、管理者以外はトップページにリダイレクトする例です。

export default defineNuxtRouteMiddleware((to) => {
  const user = useState('user')

  if (to.path.startsWith('/admin') && user.value.role !== 'admin') {
    return navigateTo('/')
  }
})

3. パラメータ検証とカスタムエラー表示

URLパラメータが特定の条件を満たさない場合に404エラーをスローする例です。

export default defineNuxtRouteMiddleware((to) => {
  if (to.params.id === '0') {
    throw createError({ statusCode: 404, statusMessage: 'ページが見つかりません' })
  }
})

このエラーは ~/error.vue でカスタム表示されます。

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

SSRとCSRの違いに注意

ミドルウェアはサーバーサイドレンダリング（SSR）とクライアントサイドレンダリング（CSR）の両方で実行されます。

• SSR時はサーバーで処理されるため、サーバー側で利用可能なAPIや状態管理を使う必要があります。
• CSR時はブラウザ上で実行されるため、ブラウザ固有のAPIや状態を利用可能です。

この違いを理解せずにブラウザ専用の処理をSSR側で実行するとエラーになります。

Hydration（ハイドレーション）との関係

ミドルウェアでリダイレクトやエラーを発生させると、ページのハイドレーション処理に影響を与えることがあります。
特に、遷移中に状態が変わるとクライアントとサーバーのレンダリング結果が不一致になる可能性があるため、状態管理は慎重に行いましょう。

パフォーマンスへの影響

ミドルウェアはページ遷移のたびに実行されるため、重い処理や非同期処理を入れすぎるとUXが悪化します。
可能な限り軽量な処理に留め、必要に応じてキャッシュや状態管理を活用してください。

まとめ

Nuxtのルートミドルウェアは、認証やアクセス制御、エラーハンドリングなどルーティングに関わる共通処理を効率的に実装できる強力な機能です。
適切に使うことでコードの重複を減らし、保守性とユーザー体験を向上させられます。
ただし、SSR/CSRの違いやパフォーマンス面の注意点を理解し、用途に応じて使い分けることが重要です。

まずはシンプルな認証チェックやリダイレクトから試し、徐々に実務に合わせて応用していきましょう。