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

NuxtのuseRuntimeConfigは、アプリケーションのランタイム時に設定値を安全かつ柔軟に管理・参照できる仕組みです。環境ごとに異なるAPIのエンドポイントや秘密情報をコードに直接書かずに扱えるため、セキュリティ向上や運用の効率化に大きく貢献します。

従来、環境変数を直接参照したり、ビルド時に設定を埋め込む方法では、クライアントに不要な秘密情報が漏れたり、設定変更のたびにビルドが必要になるなどの課題がありました。useRuntimeConfigはこれらの問題を解決し、サーバー側とクライアント側で適切に設定値を分離しつつ、動的にアクセスできる点が最大のメリットです。

まず結論：useRuntimeConfigのポイント

• サーバー専用の秘密情報はruntimeConfig直下に定義し、クライアントには公開されない
• クライアントとサーバー両方で使う設定はruntimeConfig.publicに定義し、両環境で安全にアクセス可能
• 環境変数はNUXT_プレフィックス付きで設定可能。開発・ビルド時は.envファイル、本番はプラットフォームの環境変数を利用
• useRuntimeConfig()はサーバー・クライアント両方で呼び出せるが、秘密情報はサーバー側でのみ利用可能
• app名前空間は予約済み。baseURLやcdnURLなどの特定キーがあり、カスタム設定は避けるべき

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

使うべきケース

• APIのベースURLや認証トークンなど、環境ごとに変わる設定を管理したいとき
• 秘密情報をクライアントに漏らさずにサーバー側で安全に扱いたいとき
• ビルド後も環境変数を切り替えたい（例：本番環境の設定を動的に変えたい）場合
• クライアントとサーバーで共通の設定値を使いたいが、秘密情報は分離したい場合

使わない方がよいケース

• 完全に静的な設定で、ビルド時に決まっていて変更不要な値（この場合はnuxt.config.tsの通常設定で十分）
• クライアントに絶対に公開したくない情報を誤ってpublicに入れてしまうリスクがある場合
• ランタイム設定の切り替えが不要で、環境変数を直接参照するだけで十分な場合

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

1. APIのベースURLを環境ごとに切り替える

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE || 'https://api.example.com'
    }
  }
})

// composables/useApi.ts
export const useApi = () => {
  const config = useRuntimeConfig()
  const baseURL = config.public.apiBase

  const fetchData = async () => {
    return await $fetch('/data', { baseURL })
  }

  return { fetchData }
}

2. サーバー側で秘密のAPIトークンを使う

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: process.env.NUXT_API_SECRET || 'default-secret'
  }
})

// server/api/secure-data.ts
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig(event)
  const secret = config.apiSecret

  const data = await $fetch('https://secure.api.com/data', {
    headers: { Authorization: `Bearer ${secret}` }
  })

  return data
})

3. CDNのURLを動的に切り替える

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      cdnURL: process.env.NUXT_PUBLIC_CDN_URL || 'https://cdn.example.com'
    }
  }
})

// components/ImageDisplay.vue
<script setup lang="ts">
const config = useRuntimeConfig()
const cdnURL = config.public.cdnURL
const imageUrl = `${cdnURL}/images/sample.jpg`
</script>

<template>
  <img :src="imageUrl" alt="Sample Image" />
</template>

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

1. SSRとCSRでのアクセス制御

useRuntimeConfig()はサーバー・クライアント両方で呼べますが、runtimeConfig直下の値はクライアントには送られません。秘密情報はサーバー側でのみ利用可能です。誤って秘密情報をpublicに入れるとクライアントに漏洩するため注意が必要です。

2. Hydration時の差異に注意

サーバーとクライアントでuseRuntimeConfig()の値が異なると、Hydrationエラーの原因になります。特にpublicに入れた値は両環境で同じである必要があります。動的に変わる値をpublicに入れる場合は慎重に設計しましょう。

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

useRuntimeConfig()自体は軽量ですが、頻繁にAPIのベースURLを切り替えたり、複雑なロジックを組み込むとパフォーマンスに影響する可能性があります。設定値はできるだけシンプルに保つことが望ましいです。

4. 環境変数の管理

• .envファイルは開発・ビルド時にのみ有効で、本番環境ではプラットフォームの環境変数を使うべきです。
• NUXT_プレフィックスを付けることでNuxtが自動的にランタイム設定に反映します。
• 環境変数の変更は再ビルドなしに反映されるわけではないため、動的に切り替えたい場合は別途工夫が必要です。

まとめ

NuxtのuseRuntimeConfigは、環境ごとに異なる設定を安全かつ柔軟に管理できる強力な機能です。サーバー専用の秘密情報とクライアントに公開可能な設定を明確に分離し、運用の安全性と効率性を高めます。実務ではAPIのベースURL切り替えや秘密トークンの管理、CDN URLの動的設定などで活用されることが多いです。

ただし、SSR/CSR間の値の整合性や環境変数の管理には注意が必要です。正しく使えばNuxtアプリの品質向上に大きく寄与するため、ぜひ理解を深めて活用してください。