NuxtのuseResponseHeaderとは？〜レスポンスヘッダー制御の強力な味方〜

Webアプリケーション開発において、HTTPレスポンスヘッダーはセキュリティやキャッシュ制御、カスタム情報の伝達など多様な役割を担います。Nuxtではサーバーサイドレンダリング（SSR）を活用する際に、レスポンスヘッダーを柔軟に操作できることが重要です。useResponseHeaderは、そんなレスポンスヘッダーの設定をページやミドルウェア、プラグインなどから簡単に行える便利なコンポーザブルです。

この補足記事では、useResponseHeaderの基本的な使い方から、実務での活用例、注意すべきポイントまで丁寧に解説します。初〜中級のNuxtユーザーがレスポンスヘッダー制御を理解し、効果的に活用できるようになることを目指しています。

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

• useResponseHeaderはサーバーサイドでレスポンスヘッダーを設定するためのリアクティブなAPI
• ページ単位やミドルウェア、プラグインからヘッダーを動的に追加・変更可能
• SSR時にのみ有効で、クライアントサイドでは効果がない
• セキュリティ強化（CSPやHSTS）、キャッシュ制御、カスタムヘッダー付与に最適
• ヘッダー名は大文字・小文字を区別せず設定できるが、慣例に従うことが望ましい

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

使うべきケース

• ページごとに異なるヘッダーを設定したいとき
  例えば、特定のページだけキャッシュを無効化したい、あるいはカスタムトラッキングヘッダーを付与したい場合。

• ミドルウェアで共通のヘッダーを全ページに付与したいとき
  セキュリティヘッダー（CSP、X-Frame-Optionsなど）を全ページに一括設定する際に便利。

• プラグインやサーバーサイドロジックで動的にヘッダーを制御したいとき
  APIレスポンスの条件に応じてヘッダーを変えたい場合など。

使わない方がよいケース

• クライアントサイドのみで完結する処理
  useResponseHeaderはSSR時のレスポンスヘッダー制御用なので、CSRのみの環境では効果がありません。

• 静的サイト生成（SSG）での利用
  静的ファイル配信時はサーバーのレスポンスヘッダーはWebサーバー側で設定するのが一般的です。

• 大量のヘッダーを頻繁に変更するケース
  パフォーマンスやキャッシュの観点から、必要最低限のヘッダー設定に留めることが望ましいです。

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

1. ページ単位でカスタムヘッダーを設定する

特定のページだけにカスタムヘッダーを付与し、外部サービスやブラウザに情報を伝えたい場合。

<script setup>
// pages/custom-header.vue
const header = useResponseHeader('X-Custom-Page');
header.value = 'CustomHeaderValue';
</script>

<template>
  <h1>カスタムヘッダー付きページ</h1>
  <p>このページのレスポンスには "X-Custom-Page" ヘッダーが含まれます。</p>
</template>

2. ミドルウェアで全ページにセキュリティヘッダーを付与する

全ページ共通のセキュリティ強化のため、ミドルウェアでヘッダーを設定。

// middleware/security-headers.ts
export default defineNuxtRouteMiddleware(() => {
  const csp = useResponseHeader('Content-Security-Policy');
  csp.value = "default-src 'self'; img-src https://images.example.com";
  
  const hsts = useResponseHeader('Strict-Transport-Security');
  hsts.value = 'max-age=63072000; includeSubDomains; preload';
});

3. APIレスポンスの条件に応じてヘッダーを動的に変更する

プラグインやサーバーサイドロジックで、ユーザーの状態に応じてヘッダーを変える例。

// plugins/response-header.ts
export default defineNuxtPlugin(() => {
  const userIsPremium = true; // 例として判定
  const header = useResponseHeader('X-User-Type');
  header.value = userIsPremium ? 'Premium' : 'Standard';
});

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

SSRとCSRの違いに注意

useResponseHeaderはサーバーサイドでのレスポンスヘッダー設定用です。クライアントサイドでの実行時には効果がありません。CSRのみの環境やクライアント遷移時にヘッダーを変えたい場合は別の方法を検討してください。

Hydration時の副作用に注意

ヘッダーはSSR時に決定されるため、クライアント側での状態変化がレスポンスヘッダーに反映されることはありません。動的にヘッダーを変えたい場合は、サーバーサイドでの判定ロジックを工夫しましょう。

パフォーマンスとキャッシュ制御

ヘッダーの設定はレスポンス全体の挙動に影響します。特にキャッシュ関連のヘッダーは誤設定するとパフォーマンス低下や意図しないキャッシュ動作を招くため、設定内容は慎重に検討してください。

ヘッダー名の大文字・小文字

HTTPヘッダーは大文字・小文字を区別しませんが、慣例的に単語の頭文字を大文字にするスタイルが一般的です。可読性のためにも慣例に従うことをおすすめします。

まとめ

useResponseHeaderはNuxtのSSR環境でレスポンスヘッダーを柔軟に制御できる強力なツールです。ページ単位やミドルウェア、プラグインから簡単にヘッダーを設定できるため、セキュリティ強化やキャッシュ制御、カスタム情報の伝達に役立ちます。

ただし、SSR専用のAPIであることやパフォーマンス面の注意点を理解した上で使うことが重要です。実務では用途に応じて適切に使い分け、Nuxtアプリケーションの品質向上に役立ててください。