Nuxt3入門(第5回) - アプリケーションの設定情報を管理する

| 5 min read
Author: noboru-kudo noboru-kudoの画像

前回はNuxt3のルーティング機能について見てきました。

今回はNuxt3が提供する設定情報の管理機能を見ていきます。
Nuxt3では、アプリケーションの設定はRuntime Config(またはApp Config)を通して管理され、グローバルに参照できます。
とはいえ、パスワード等の機密性の高い設定は、ブラウザ上では参照不可とするべきです。
このため、Nuxtでは設定情報をpublic/privateで区別し、privateな設定はサーバーサイドでのみ参照可能となるセキュリティ面も配慮されています。

なお、ここでいう設定情報はNuxt自体のものではなく、アプリケーション内で利用する設定情報です。

Contents

Runtime Config

#

Nuxt3で導入されたApp Configは後述しますが、アプリケーションの設定は基本的にはRuntime Configを使います。
Runtime Configは、アプリケーションのnuxt.config.tsに記述します。

以下はサンプルの記述例です。

export default defineNuxtConfig({
runtimeConfig: {
// public設定
public: {
foo: 'foo-setting',
},
// private設定
secret: 'my-secret-value',
db: {
user: 'mamezou',
password: 'super-secret'
},
}
})

runtimeConfig配下に任意の設定値をキーバリューで記述します。任意の階層でネストして記述も可能です。

runtimeConfig.public配下に記述するとpublicな設定となり、サーバーサイド、クライアントサイド双方で参照可能です。
一方でruntimeConfig直下に記述した場合はprivateな設定となり、サーバーサイドでのみ参照可能となります。

実際にpublic/privateの違いを確認するために、以下のVueコンポーネントを作成します。

<script setup lang="ts">
const runtimeConfig = useRuntimeConfig();
const env = process.server ? 'Server' : 'Client';
console.log(`[${env}] public.foo: ${runtimeConfig.public.foo}`);
console.log(`[${env}] secret: ${runtimeConfig.secret}`);
console.log(`[${env}] db.user: ${runtimeConfig.db?.user}`);
console.log(`[${env}] db.password: ${runtimeConfig.db?.password}`);
</script>

<template>
<div>No Contents</div>
</template>

Nuxtが提供するuseRuntimeConfig Composableを利用して、Runtime Configを取得します。
もちろん、これもNuxt3のAuto Importの対象なのでimport文の記述は不要ですし、IDEのコード補完も有効です。

ここでは、先程設定した設定をコンソールログに出力するだけのものです。これでNuxtを起動すると出力結果は以下のようになります。

  • サーバーサイド
[Server] public.foo: foo-setting
[Server] secret: my-secret-value
[Server] db.user: mamezou
[Server] db.password: super-secret
  • クライアントサイド(Dev Tool)
[Client] public.foo: foo-setting
[Client] secret: undefined
[Client] db.user: undefined
[Client] db.password: undefined

サーバーサイドではprivateな設定を含め全て値が参照できていますが、クライアントサイドではpublicな設定のみ参照可能で、privateな設定はundefinedと参照不可となっています。
このようにpublic/privateを使い分けることで、設定情報の機密レベルに応じた可視性の調整が可能になります。

なお、ここではVueコンポーネントで確認しましたが、Runtime Configはserverに配置したサーバーサイドのAPIからも参照可能です。

Information

ここでは説明しませんでしたが、Runtime Configにはpublic/private以外にもデフォルトでappネームスペースとしてbaseURL等の設定が含まれています。
これらもpublic同様にクライアントサイドへ公開されます。

appネームスペースの詳細は公式ドキュメントを参照してください。

環境変数による切り替え

#

先程はnuxt.config.tsのRuntime Configとして設定情報を記述することで、アプリケーションの任意の場所で設定値を参照できることを確認しました。

一般的にアプリケーションは開発、テスト、商用環境等のステージに応じて各種設定が異なることが多いかと思います。
nuxt.config.tsは通常のTypeScriptソースコードでもありますので、切替ロジックを入れることはできますがスマートな方法とは言えません。
また、nuxt.config.tsはソースコード管理の対象に含まれますので、機密性の高い設定値を直接記述するのは理想的なやり方とは言えません。

このような状況でよく使わる手段はOSの環境変数です。Nuxtでも環境変数のサポートがあります。

環境変数でRuntime Configを上書きする場合は、環境変数にNUXT_をプリフィックス(デフォルト)として、設定値のキーを大文字のスネークケースに変換して指定します[1]

先程privateな設定として記述したsecretを環境変数で上書きする場合は、以下のようになります。

# 開発時
NUXT_SECRET=local-secret npm run dev

# サーバーサイドレンダリング
npm run build
NUXT_SECRET=prod-secret node .output/server/index.mjs

# プリレンダリング
NUXT_SECRET=prod-prerendering-secret npm run generate
# dist配下をホスティング

このようにすると、runtimeConfig.secretはそれぞれの環境変数値で上書きされます。
注意点としては、環境変数のみではRuntime Configに反映されません。値は空文字でもいいので、Runtime Configへのフォールバック指定は必要です。

dotenvサポート

環境変数が多い場合は、以下のように.envファイルを用意して、取り込むことが可能です(dotenvサポート)。

NUXT_SECRET=prod-secret

ただし、dotenvサポートが有効なのはビルド時のみです。
ビルド後にサーバーサイドで実行する場合は、source .env && node .output/server/index.mjs等、.envファイルの内容を環境変数として設定する必要があります。

App Config

#

先程のRuntime Configは開発モード(npm run dev)で起動した場合、nuxt.config.tsの変更を検知するとNuxtアプリケーションは再起動します。
このため、アプリケーションの規模によっては、変更反映まで時間がかかります。

この点を解消するために、Nuxt3では新しくApp Configが導入されました。

App Configは、nuxt.config.tsではなく、専用のファイルapp.config.tsを作成します。

export default defineAppConfig({
bar: 'app-config-value',
})

defineAppConfigを使い、その中に設定情報を記述します。こちらもRuntime Config同様にネストした構造も可能です。
注意点として、App ConfigはRuntime Configのようにprivate/publicの区別がなく、クライアントサイドにも公開されます。機密性の高い情報はここではなく、Runtime Configのprivateな設定とする必要があります。

これを利用するコードは以下のようになります。

const appConfig = useAppConfig();
console.log(`[${env}] bar: ${appConfig.bar}`);

Nuxtが提供するuseAppConfig Composableを使ってApp Configを取得します。
設定値の参照はRuntime Configと同じで、IDEのコード補完も有効です。

App Configは開発モードで実行(npm run dev)した場合に、HMR(Hot Module Replacement)が有効となり、ソースコード同様に変更はすぐに反映されます。
このため、ローカル環境での開発体験としてはより良いものとなっています。

ただし、現時点(RC.11)ではApp Configの設定を環境変数で置換できませんでした。
App Configは、環境依存でない設定が対象で、どちらかというとソースコードに近い扱いとなっているようです(HMR重視)。

App Configは最近導入されており、GAバージョンでは変更があるかもしれません(GAバージョンリリース次第見直し予定です)。
利用時には最新の状況をご確認ください。

まとめ

#

今回はNuxt3が提供する設定情報について見てきました。
public/privateによる設定情報の可視性制御や、環境変数による切り替えは抑えておきたいポイントです。

次回はエラーハンドリングについて見ていきます。


  1. ネストした構造の場合は._に変換します。 ↩︎

豆蔵デベロッパーサイト - 先週のアクセスランキング
  1. Nuxt3入門(第1回) - Nuxtがサポートするレンダリングモードを理解する (2022-09-25)
  2. 自然言語処理初心者が「GPT2-japanese」で遊んでみた (2022-07-08)
  3. GitHub Codespaces を使いはじめる (2022-05-18)
  4. Jest再入門 - 関数・モジュールモック編 (2022-07-03)
  5. ORマッパーのTypeORMをTypeScriptで使う (2022-07-27)
  6. Nuxt3入門(第4回) - Nuxtのルーティングを理解する (2022-10-09)
  7. Nuxt3入門(第3回) - ユニバーサルフェッチでデータを取得する (2022-10-06)
  8. 第1回 OpenAPI Generator を使ったコード生成 (2022-06-04)
  9. Nuxt3入門(第8回) - Nuxt3のuseStateでコンポーネント間で状態を共有する (2022-10-28)
  10. Nuxt3入門(第2回) - 簡単なNuxtアプリケーションを作成する (2022-10-02)