app.config.ts

Реактивная конфигурация приложения через файл app.config.

Nuxt использует файл app.config для реактивной конфигурации: значения можно менять в рантайме в жизненном цикле приложения, из плагина Nuxt и при правках в режиме разработки (горячая замена модулей, HMR).

Настройки в рантайме задаются в app.config.ts (или .js / .mjs).

app.config.ts
export default defineAppConfig({
  foo: 'bar',
})
Не помещайте никаких секретных значений в файл app.config. Он доступен для клиентского бандла пользователя.
При пользовательском srcDir положите app.config в корень нового пути srcDir.

Использование

Чтобы предоставить доступ к конфигурации и переменным окружения остальной части приложения, вам необходимо определить конфигурацию в файле app.config.

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

Теперь theme доступен и при SSR, и в браузере через композабл useAppConfig.

pages/index.vue
<script setup lang="ts">
const appConfig = useAppConfig()

console.log(appConfig.theme)
</script>

Утилита updateAppConfig обновляет app.config во время выполнения.

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

const newAppConfig = { foo: 'baz' }

updateAppConfig(newAppConfig)

console.log(appConfig) // { foo: 'baz' }
</script>
Подробнее об утилите updateAppConfig.

Типизация конфигурации приложения

Nuxt пытается автоматически сгенерировать интерфейс TypeScript из переданной конфигурации приложения, поэтому типизировать её вручную обычно не нужно.

Иногда типы всё же задают вручную. Ниже — два типичных случая.

Ввод конфигурации приложения

AppConfigInput может использоваться авторами модулей, которые объявляют допустимые параметры input при настройке конфигурации приложения. Это не повлияет на тип useAppConfig().

index.d.ts
declare module 'nuxt/schema' {
  interface AppConfigInput {
    /** Конфигурация темы */
    theme?: {
      /** Основной цвет приложения */
      primaryColor?: string
    }
  }
}

// Всегда важно убедиться, что вы импортируете/экспортируете что-либо при расширении типа.
export {}

Вывод конфигурации приложения

Чтобы типизировать результат useAppConfig(), расширьте интерфейс AppConfig.

Будьте осторожны при типизации AppConfig: вы перезапишете типы, которые Nuxt выводит из фактической конфигурации приложения.
index.d.ts
declare module 'nuxt/schema' {
  interface AppConfig {
    // Это полностью заменит существующее выведенное свойство `theme`
    theme: {
      // Здесь можно задать более узкие типы, чем выводит Nuxt,
      // например, типы строковых литералов.
      primaryColor?: 'red' | 'blue'
    }
  }
}

// Всегда важно убедиться, что вы импортируете/экспортируете что-либо при расширении типа.
export {}

Стратегия слияния

Nuxt использует специальную стратегию слияния для AppConfig в слоях вашего приложения.

Эта стратегия реализуется через слияние с пользовательскими функциями в defu: для каждого ключа в app.config, значение которого — массив, можно задать свою логику объединения.

Функцию слияния (merger) можно использовать только в расширенных слоях, а не в основном файле app.config проекта.

Вот пример того, как это можно использовать:

export default defineAppConfig({
  // Значение массива по умолчанию
  array: ['hello'],
})

Известные ограничения

Начиная с Nuxt v3.3, файл app.config.ts разделяется с Nitro, из-за чего действуют следующие ограничения:

  1. Нельзя напрямую импортировать компоненты Vue в app.config.ts.
  2. Некоторые автоимпорты недоступны в контексте Nitro.

Эти ограничения возникают потому, что Nitro обрабатывает конфигурацию приложения без полной поддержки компонентов Vue.

Хотя в качестве обходного пути можно использовать плагины Vite в конфигурации Nitro, такой подход не рекомендуется:

nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    vite: {
      plugins: [vue()],
    },
  },
})
Использование этого обходного пути может привести к непредсказуемому поведению и ошибкам. Плагин Vue — один из многих, недоступных в контексте Nitro.

Связанные задачи на GitHub:

В Nitro v3 эти ограничения планируют убрать вместе с изменением модели app config. Следить за прогрессом можно в этом pull request.