brand logo

ドキュメント

Version 33.17Version 44.10

app.config.ts

アプリケーション内でリアクティブな設定を公開するための App Config ファイル。

Nuxt は app.config 設定ファイルを提供しており、ライフサイクル内や nuxt プラグインを使用して、HMR（ホットモジュールリプレースメント）で編集することで、アプリケーション内でリアクティブな設定を公開し、実行時に更新することができます。

app.config.ts ファイルを使用して、簡単に実行時のアプリ設定を提供できます。拡張子は .ts、.js、または .mjs のいずれかを使用できます。

app.config.ts
export default defineAppConfig({
  foo: 'bar'
})

app.config ファイル内に秘密の値を入れないでください。これはユーザークライアントバンドルに公開されます。

カスタムの srcDir を設定する際は、新しい srcDir パスのルートに app.config ファイルを配置することを確認してください。

使用法

アプリの他の部分に設定と環境変数を公開するには、app.config ファイルで設定を定義する必要があります。

app.config.ts
export default defineAppConfig({
  theme: {
    primaryColor: '#ababab'
  }
})

これで、サーバーレンダリング時とブラウザで useAppConfig コンポーザブルを使用して theme に普遍的にアクセスできます。

pages/index.vue
const appConfig = useAppConfig()

console.log(appConfig.theme)

updateAppConfig ユーティリティを使用して、実行時に app.config を更新できます。

pages/index.vue
const appConfig = useAppConfig() // { foo: 'bar' }

const newAppConfig = { foo: 'baz' }

updateAppConfig(newAppConfig)

console.log(appConfig) // { foo: 'baz' }
こちらも参照 api > utils > update-app-config

App Config の型付け

Nuxt は提供されたアプリ設定から TypeScript インターフェースを自動的に生成しようとするため、自分で型を付ける必要はありません。

しかし、場合によっては自分で型を付けたいこともあります。型付けしたいことは2つあります。

App Config Input

AppConfigInput は、アプリ設定を設定する際の有効な 入力 オプションを宣言するモジュール作成者によって使用されるかもしれません。これは useAppConfig() の型には影響しません。

index.d.ts
declare module 'nuxt/schema' {
  interface AppConfigInput {
    /** テーマ設定 */
    theme?: {
      /** アプリの主要色 */
      primaryColor?: string
    }
  }
}

// 型を拡張する際には、何かをインポート/エクスポートすることを常に確認することが重要です
export {}

App Config Output

useAppConfig() を呼び出した結果に型を付けたい場合は、AppConfig を拡張します。

AppConfig に型を付ける際は注意が必要です。実際に定義されたアプリ設定から Nuxt が推測する型を上書きしてしまいます。

index.d.ts
declare module 'nuxt/schema' {
  interface AppConfig {
    // これにより、既存の推測された `theme` プロパティが完全に置き換えられます
    theme: {
      // この値により具体的な型を追加したい場合、例えば文字列リテラル型など
      primaryColor?: 'red' | 'blue'
    }
  }
}

// 型を拡張する際には、何かをインポート/エクスポートすることを常に確認することが重要です
export {}

マージ戦略

Nuxt はアプリケーションのレイヤー内で AppConfig に対してカスタムマージ戦略を使用します。

この戦略は Function Merger を使用して実装されており、app.config 内のすべてのキーに対してカスタムマージ戦略を定義することができます。

関数マージャーは拡張レイヤーでのみ使用でき、プロジェクトのメイン app.config では使用できません。

以下はその使用例です：

export default defineAppConfig({
  // デフォルトの配列値
  array: ['hello'],
})

既知の制限

Nuxt v3.3 以降、app.config.ts ファイルは Nitro と共有されており、以下の制限があります：

  1. app.config.ts で Vue コンポーネントを直接インポートできません。
  2. 一部の自動インポートは Nitro コンテキストで利用できません。

これらの制限は、Nitro が完全な Vue コンポーネントサポートなしでアプリ設定を処理するために発生します。

Nitro 設定で Vite プラグインを使用することで回避策を取ることは可能ですが、このアプローチは推奨されません：

nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    vite: {
      plugins: [vue()]
    }
  }
})

この回避策を使用すると、予期しない動作やバグが発生する可能性があります。Vue プラグインは Nitro コンテキストで利用できない多くのプラグインの一つです。

関連する問題：

Nitro v3 はアプリ設定のサポートを削除することでこれらの制限を解決します。 進捗状況はこのプルリクエストで追跡できます。

tips

このセクションは公式ドキュメントの翻訳ではなく、本サイト独自の補足記事です。

Nuxtのapp.config.tsとは？〜リアクティブなアプリ設定の管理を簡単に〜

Nuxt 3では、app.config.tsを使うことで、アプリケーション全体で共有する設定値をリアクティブに管理できます。これにより、環境変数やテーマカラーなどの設定を一元管理しつつ、実行時に動的に更新できるため、開発効率やUXの向上に役立ちます。

従来は環境変数やプラグインで設定を分散管理しがちでしたが、app.config.tsを使うと設定の一元化とリアクティブな更新が可能になり、コードの保守性が大幅に向上します。

まず結論：app.config.tsのポイント

  • リアクティブなアプリ設定を一元管理できる
    app.config.tsに定義した設定は、useAppConfig()でどこからでもアクセス可能。

  • 実行時に設定を動的に更新できる
    updateAppConfig()を使えば、HMRやユーザー操作に応じて設定を変更可能。

  • 型安全に設定を扱える
    TypeScriptの型拡張で設定の型を明示し、開発時の補完や型チェックが可能。

  • サーバー・クライアント両方で同じ設定を共有
    SSR時もブラウザ側も同じ設定を参照できるため、一貫性が保てる。

  • ただし秘密情報は含めないこと
    設定はクライアントバンドルに含まれるため、APIキーなどの秘密情報は別管理が必須。

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

使うべきケース

  • アプリ全体で共通のテーマカラーやUI設定を管理したいとき
  • ユーザーの操作や外部イベントに応じて設定を動的に切り替えたいとき
  • 複数のレイヤーやモジュールで設定をマージしながら管理したいとき
  • SSRとCSRで同じ設定を共有し、一貫した動作を実現したいとき

避けるべきケース

  • APIキーやパスワードなどの秘密情報を格納したい場合（クライアントに公開されるため）
  • Vueコンポーネントや複雑なロジックを直接設定に含めたい場合（Nitroの制限により非推奨）
  • 設定の更新頻度が非常に高く、パフォーマンスに影響が出る可能性がある場合

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

1. テーマカラーの一元管理と動的切り替え

// app.config.ts
export default defineAppConfig({
  theme: {
    primaryColor: '#007bff'
  }
})

<script setup lang="ts">
const appConfig = useAppConfig()

function changeThemeColor(color: string) {
  updateAppConfig({
    theme: {
      primaryColor: color
    }
  })
}
</script>

<template>
  <div :style="{ color: appConfig.theme.primaryColor }">
    テーマカラーが反映されます
  </div>
  <button @click="changeThemeColor('#e91e63')">ピンクに変更</button>
</template>

この例では、app.config.tsで定義したテーマカラーをリアクティブに参照し、ボタン操作で色を動的に切り替えています。

2. 多言語対応の設定管理

// app.config.ts
export default defineAppConfig({
  i18n: {
    defaultLocale: 'ja',
    supportedLocales: ['ja', 'en', 'fr']
  }
})

const appConfig = useAppConfig()

console.log('対応言語:', appConfig.i18n.supportedLocales.join(', '))

多言語対応の設定を一元管理し、必要に応じてUIやロジックで参照できます。

3. レイヤーごとの設定マージ

// layers/base/app.config.ts
export default defineAppConfig({
  features: ['login', 'signup']
})

// app.config.ts (プロジェクトルート)
export default defineAppConfig({
  features: () => ['dashboard'] // マージ関数で上書き
})

レイヤーごとに設定を分割し、マージ戦略を活用して柔軟に設定を組み合わせられます。

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

1. 秘密情報を含めない

app.config.tsの内容はクライアントバンドルに含まれるため、APIキーやパスワードなどの秘密情報は絶対に入れないでください。これらは環境変数やサーバー専用の設定で管理しましょう。

2. Nitroの制限に注意

Nuxt v3.3以降、app.config.tsはNitroサーバーと共有されますが、Vueコンポーネントの直接インポートや一部の自動インポートは利用できません。これにより、設定ファイル内でVue固有のコードを使うことは避ける必要があります。

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

updateAppConfig()で頻繁に設定を更新すると、リアクティブな依存先が多い場合にパフォーマンス低下を招くことがあります。更新は必要最低限に留め、不要な再レンダリングを避けましょう。

4. 型定義の上書きに注意

AppConfigの型を拡張する際、既存の推測型を完全に置き換えてしまうことがあります。型を拡張する場合は、既存の型を尊重しつつ必要な部分だけを追加・修正するように心がけてください。

まとめ

Nuxtのapp.config.tsは、アプリケーションの設定をリアクティブかつ一元管理できる強力な仕組みです。テーマや多言語設定、機能フラグなどを簡単に共有・更新できるため、開発効率とUXの向上に大きく貢献します。

ただし、秘密情報の管理やNitroの制限、パフォーマンス面の注意点を理解した上で適切に使うことが重要です。型定義も活用して安全かつ保守性の高いコードを書くことをおすすめします。

Nuxtの公式ドキュメントと合わせて、本記事の内容を参考にapp.config.tsを効果的に活用してください。

© 2016–PRESENT Nuxt Labs https://nuxt.com

※このページは Nuxt.js 公式ドキュメントの翻訳ページです。

公式ドキュメントの該当ページはこちら：
https://nuxt.com/docs/3.x/guide/directory-structure/app-config