NuxtのuseRequestHeaderとは？〜何が嬉しいのか〜

NuxtのuseRequestHeaderは、サーバーサイドレンダリング（SSR）環境で受信したHTTPリクエストのヘッダー情報に簡単にアクセスできるコンポーザブルです。これにより、認証トークンやカスタムヘッダーの値を取得し、ページやミドルウェア、プラグインの中で条件分岐や処理を行うことが可能になります。

従来、サーバーサイドでヘッダー情報を取得するには複雑な設定やAPIの呼び出しが必要でしたが、useRequestHeaderを使うことでコードがシンプルになり、開発効率が大幅に向上します。

また、クライアントサイドではヘッダー情報が取得できないため、SSR時の処理に限定して安全に利用できる点も特徴です。

まず結論：useRequestHeaderのポイント

• サーバーサイドで受信リクエストの特定ヘッダーを簡単に取得できる
• クライアントサイドでは常にundefinedを返すため、SSR限定の処理に使う
• 認証やアクセス制御、カスタムヘッダーの判定に最適
• ページ、ミドルウェア、プラグインなどNuxtのあらゆる場所で利用可能
• ヘッダー名は小文字で指定するのが一般的（HTTPヘッダーは大文字小文字を区別しないが慣習的に小文字推奨）

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

使うべきケース

• 認証トークンの検証
  APIリクエストやページアクセス時にauthorizationヘッダーを読み取り、ユーザー認証を行う場合。

• カスタムヘッダーによる機能切り替え
  クライアントから送られる特定のヘッダー値に応じて、SSR時のレンダリング内容を変えたいとき。

• ミドルウェアでのアクセス制御
  ルート遷移時にヘッダー情報を元にアクセス権限を判定し、リダイレクトやエラーページ表示を行う場合。

使わない方がよいケース

• クライアントサイドでのヘッダー取得
  ブラウザ環境ではuseRequestHeaderはundefinedを返すため、クライアント側でヘッダー情報を使いたい場合は別の方法が必要。

• リクエストボディやクエリパラメータの取得
  これらはuseRequestHeaderでは取得できないため、別のAPIやコンポーザブルを使う。

• 頻繁に変わるヘッダー情報のリアルタイム監視
  SSR時の一度きりの取得に向いているため、動的に変化するヘッダーをクライアントで監視したい場合は不向き。

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

1. 認証ミドルウェアでの利用

認証トークンがリクエストヘッダーに含まれているかをチェックし、なければアクセス拒否する例です。

// middleware/authenticated.ts
export default defineNuxtRouteMiddleware(() => {
  const token = useRequestHeader('authorization')
  if (!token) {
    return navigateTo('/login')
  }
})

このようにミドルウェアで使うことで、認証が必要なページへのアクセス制御を簡単に実装できます。

2. APIプラグインでのヘッダー取得

サーバーサイドでAPIリクエストを代理送信する際に、元のリクエストヘッダーを引き継ぐ例です。

// plugins/api.ts
export default defineNuxtPlugin(() => {
  const token = useRequestHeader('authorization')
  const apiClient = $fetch.create({
    baseURL: 'https://api.example.com',
    headers: {
      authorization: token || ''
    }
  })
  return { apiClient }
})

これにより、ユーザーの認証情報をAPIリクエストに付与できます。

3. 多言語対応でのAccept-Language判定

リクエストヘッダーのaccept-languageを読み取り、SSR時に適切な言語でレンダリングする例です。

// composables/useLocale.ts
export function useLocale() {
  const lang = useRequestHeader('accept-language')?.split(',')[0] || 'en'
  return lang
}

このようにヘッダーを活用してユーザーの言語環境に合わせた表示が可能です。

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

1. クライアントサイドでのundefined

useRequestHeaderはブラウザ環境では常にundefinedを返します。
そのため、クライアントサイドでヘッダー情報を使う処理を書くとエラーや意図しない挙動になることがあります。

2. SSRとHydrationの不整合

SSR時にヘッダー情報を元にレンダリングした内容と、クライアント側でのHydration時の状態が異なると、Vueの警告やUIの不整合が発生します。

例えば、SSRで認証済みと判断して表示したコンテンツが、クライアント側でuseRequestHeaderがundefinedになるため非認証状態と判断されるケースです。

3. パフォーマンスへの影響

useRequestHeader自体は軽量ですが、ヘッダーの値を元に複雑な処理や外部API呼び出しをSSR中に行うとレスポンス速度が低下します。

まとめ

useRequestHeaderはNuxtのSSR環境でリクエストヘッダーに簡単にアクセスできる強力なツールです。認証やアクセス制御、多言語対応など多様な場面で活用できますが、クライアントサイドで使えない点やSSRとCSRの状態不整合に注意が必要です。

実務ではミドルウェアやプラグインでの利用が多く、適切に使うことでコードの可読性と保守性が向上します。ヘッダー情報を活用したサーバーサイド処理を検討している方は、ぜひ本記事のポイントを参考にしてください。