app.config.ts

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

В Nuxt файл app/app.config.ts задаёт реактивную конфигурацию приложения; её можно обновлять в рантайме в хуках жизненного цикла или через плагин, с поддержкой HMR.

Расширения файла: .ts, .js или .mjs.

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

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

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

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

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

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

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

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

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

const newAppConfig = { foo: 'baz' }

updateAppConfig(newAppConfig)

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

Типизация App Config

Nuxt пытается автоматически вывести TypeScript-интерфейс из app.config. При необходимости типы можно задать вручную.

Входной App Config (AppConfigInput)

AppConfigInput нужен авторам модулей, чтобы описать допустимые входные опции при задании app config. На тип результата useAppConfig() это не влияет.

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

// При расширении типов нужен import/export
export {}

Выходной App Config (AppConfig)

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

При типизации AppConfig вы перезаписываете типы, которые Nuxt выводит из вашего app.config.
index.d.ts
declare module 'nuxt/schema' {
  interface AppConfig {
    // Это полностью заменит выведенное свойство theme
    theme: {
      primaryColor?: 'red' | 'blue'
    }
  }
}

export {}

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

В слоях Nuxt использует свою стратегию слияния для AppConfig через Function Merger: для каждого ключа с массивом можно задать свою функцию слияния.

Function merger доступен только в расширяющих слоях, не в основном app.config проекта.

Пример:

export default defineAppConfig({
  array: ['hello'],
})

Ограничения

Начиная с Nuxt v3.3, app.config.ts используется и в Nitro, из-за чего:

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

Nitro обрабатывает app config без полной поддержки Vue.

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

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

Связанные issues:

В Nitro v3 эти ограничения планируется снять, убрав поддержку app config в Nitro. Прогресс: этот PR.