# app.config.ts

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

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

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

```ts [app.config.ts]twoslash
export default defineAppConfig({
  foo: 'bar',
})
```

<caution>

Не помещайте никаких секретных значений в файл `app.config`. Он доступен для клиентского бандла пользователя.

</caution>

<note>

При пользовательском [`srcDir`](/docs/3.x/api/nuxt-config#srcdir) положите `app.config` в корень нового пути `srcDir`.

</note>

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

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

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

Теперь `theme` доступен и при SSR, и в браузере через композабл [`useAppConfig`](/docs/3.x/api/composables/use-app-config).

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

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

Утилита [`updateAppConfig`](/docs/3.x/api/utils/update-app-config) обновляет `app.config` во время выполнения.

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

const newAppConfig = { foo: 'baz' }

updateAppConfig(newAppConfig)

console.log(appConfig) // { foo: 'baz' }
</script>
```

<read-more to="/docs/3.x/api/utils/update-app-config">

Подробнее об утилите `updateAppConfig`.

</read-more>

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

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

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

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

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

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

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

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

Чтобы типизировать результат [`useAppConfig()`](/docs/3.x/api/composables/use-app-config), расширьте интерфейс `AppConfig`.

<warning>

Будьте осторожны при типизации `AppConfig`: вы перезапишете типы, которые Nuxt выводит из фактической конфигурации приложения.

</warning>

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

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

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

Nuxt использует специальную стратегию слияния для `AppConfig` в [слоях](/docs/3.x/directory-structure/layers/) вашего приложения.

Эта стратегия реализуется через [слияние с пользовательскими функциями](https://github.com/unjs/defu#function-merger) в `defu`: для каждого ключа в `app.config`, значение которого — массив, можно задать свою логику объединения.

<note>

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

</note>

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

<code-group>

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

```ts [app.config.ts]twoslash
export default defineAppConfig({
  // Перезаписать значение массива по умолчанию с помощью функции слияния
  array: () => ['bonjour'],
})
```

</code-group>

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

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

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

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

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

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

<warning>

Использование этого обходного пути может привести к непредсказуемому поведению и ошибкам. Плагин Vue — один из многих, недоступных в контексте Nitro.

</warning>

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

- [#19858](https://github.com/nuxt/nuxt/issues/19858)
- [#19854](https://github.com/nuxt/nuxt/issues/19854)

<note>

В Nitro v3 эти ограничения планируют убрать вместе с изменением модели app config.
Следить за прогрессом можно в [этом pull request](https://github.com/nitrojs/nitro/pull/2521).

</note>