NuxtのsetResponseStatusとは？〜レスポンスステータスを自在に制御する

Nuxtはサーバーサイドレンダリング（SSR）を強力にサポートしており、その中でHTTPレスポンスのステータスコードを適切に設定することは、ユーザー体験やSEO、API設計において非常に重要です。setResponseStatusは、サーバー側でレスポンスのステータスコード（例: 200, 404, 500など）やステータスメッセージを明示的に設定できるNuxtのコンポーザブル関数です。

これにより、例えば「ページが見つからない場合は404を返す」「認証エラーなら401を返す」といったレスポンス制御が簡単に実装できます。ブラウザ側では効果がないため、SSRやAPIレスポンスの制御に特化した機能といえます。

まず結論：setResponseStatusのポイント

• サーバーサイドでのみ有効：ブラウザ（クライアント）では効果がありません。
• HTTPステータスコードとメッセージを設定可能：statusCodeは必須、statusMessageはオプション。
• useRequestEventで取得したイベントオブジェクトが必要：Nuxtのサーバーコンテキスト内でのみ呼び出せる。
• エラーページやAPIレスポンスの制御に最適：404や500などのカスタムレスポンスを返せる。
• SSR時のレスポンス制御に必須のAPI：SEOやUX向上に寄与。

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

使うべきケース

• カスタムエラーページの実装時
  例えば、存在しないページにアクセスされた際に404ステータスを返しつつ、独自のエラーページを表示したい場合。

• APIレスポンスのステータス制御
  NuxtのサーバーサイドAPIで、認証失敗やバリデーションエラー時に適切なHTTPステータスを返す必要がある場合。

• SSRでのSEO対策
  検索エンジンに正しいステータスコードを返すことで、インデックスの最適化やクロールの効率化を図る場合。

使わない方がよいケース

• クライアントサイドのみの処理
  ブラウザでの動的なステータス制御はできないため、クライアント側の状態管理や表示制御は別の方法で行うべき。

• 単純なページ遷移やナビゲーション制御
  ステータスコードの設定はHTTPレスポンスに関わるため、単なる画面遷移には不要。

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

1. カスタム404ページの実装

存在しないページにアクセスされた際に、404ステータスを返しつつカスタムメッセージを設定。

const event = useRequestEvent()

if (event) {
  setResponseStatus(event, 404, 'Page Not Found')
}

このコードは、SSR時にHTTPレスポンスのステータスを404に設定し、ブラウザやクローラーに「ページが見つからない」ことを正しく伝えます。

2. APIエンドポイントでの認証エラー制御

APIで認証に失敗した場合に401 Unauthorizedを返す例。

const event = useRequestEvent()

if (event && !isAuthenticated()) {
  setResponseStatus(event, 401, 'Unauthorized')
  return { error: '認証が必要です' }
}

これにより、クライアントは認証エラーをHTTPステータスで判別でき、適切な処理を行えます。

3. サーバー内部エラーの通知

サーバー処理中に予期せぬエラーが発生した場合に500 Internal Server Errorを返す例。

const event = useRequestEvent()

try {
  // 何らかの処理
} catch (error) {
  if (event) {
    setResponseStatus(event, 500, 'Internal Server Error')
  }
  throw error
}

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

SSRとCSRの違いに注意

setResponseStatusはサーバーサイドでのみ効果を発揮します。クライアントサイドで呼び出してもステータスコードは変更されません。したがって、クライアント側でのエラーハンドリングは別途実装が必要です。

Hydration時の不整合に注意

SSRでステータスコードを設定しても、クライアント側のJavaScriptがHydration（再利用）する際に状態が異なると、UIの不整合が起きる可能性があります。サーバーとクライアントで状態を同期させる設計が重要です。

パフォーマンスへの影響

ステータスコードの設定自体は軽量ですが、エラーページのレンダリングやAPIレスポンスの処理が複雑になるとレスポンス速度に影響することがあります。必要最低限の処理に留めることが望ましいです。

useRequestEventの取得タイミング

useRequestEventはNuxtのサーバーコンテキスト内でのみ有効です。ミドルウェアやサーバーAPI、asyncDataなどのサーバー処理中に呼び出しましょう。クライアント側や非サーバーコンテキストでの呼び出しはundefinedになるためエラーになります。

まとめ

setResponseStatusはNuxtのSSR環境でHTTPレスポンスのステータスコードを柔軟に制御できる重要なAPIです。カスタムエラーページやAPIレスポンスの適切なステータス設定により、ユーザー体験の向上やSEO対策に役立ちます。一方で、クライアントサイドでは効果がないため、使うべき場面を見極めることが大切です。実務ではuseRequestEventと組み合わせてサーバーコンテキスト内で正しく使い、Hydrationの不整合やパフォーマンスにも注意しながら活用しましょう。