Runtime-конфигурация

В Nuxt конфигурация и секреты доступны через API runtime config.

Проброс в приложение

Чтобы сделать конфиг и переменные окружения доступными в приложении, определите runtime-конфигурацию в nuxt.config через опцию runtimeConfig.

nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // Приватные ключи — только на сервере
    apiSecret: '123',
    // Ключи внутри public также доступны на клиенте
    public: {
      apiBase: '/api',
    },
  },
})

Если добавить apiBase в runtimeConfig.public, Nuxt включает его в payload каждой страницы. К apiBase можно обращаться и на сервере, и в браузере.

const runtimeConfig = useRuntimeConfig()

console.log(runtimeConfig.apiSecret)
console.log(runtimeConfig.public.apiBase)
Публичный runtime config в шаблонах Vue доступен как $config.public.

Сериализация

Runtime config сериализуется перед передачей в Nitro. То, что нельзя сериализовать и десериализовать (функции, Set, Map и т.п.), не следует задавать в nuxt.config.

Вместо передачи несериализуемых объектов или функций из nuxt.config поместите код в плагин или middleware Nuxt или Nitro.

Переменные окружения

Чаще всего конфигурацию задают переменными окружения.

Nuxt CLI при разработке, сборке и generate читает файл .env. При запуске уже собранного сервера файл .env не читается.
Узнать больше Docs > 4 X > Directory Structure > Env.

Значения runtime config автоматически подменяются подходящими переменными окружения в рантайме.

Два важных условия:

  1. Нужные переменные должны быть объявлены в nuxt.config. Так произвольные переменные окружения не попадают в код приложения.
  2. Переопределить свойство runtime config может только специально именованная переменная окружения: в верхнем регистре, с префиксом NUXT_, с _ между ключами и сменой регистра.
Если задавать значения по умолчанию в runtimeConfig из других переменных окружения (например myVar из process.env.OTHER_VARIABLE), это сработает только на этапе сборки и сломается в рантайме. Лучше использовать переменные, соответствующие структуре объекта runtimeConfig.
Видео Александра Лихтера о типичной ошибке при использовании runtimeConfig.

Пример

.env
NUXT_API_SECRET=api_secret_token
NUXT_PUBLIC_API_BASE=https://nuxtjs.org
nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '', // можно переопределить через NUXT_API_SECRET
    public: {
      apiBase: '', // можно переопределить через NUXT_PUBLIC_API_BASE
    },
  },
})

Чтение

Vue-приложение

Во Vue-части Nuxt-приложения вызывайте useRuntimeConfig().

Поведение на клиенте и на сервере различается:
  • На клиенте доступны только ключи из runtimeConfig.public и runtimeConfig.app (внутреннее использование Nuxt); объект можно менять, он реактивен.
  • На сервере доступен весь runtime config, но он только для чтения, чтобы не было общего контекста между запросами.
app/pages/index.vue
<script setup lang="ts">
const config = useRuntimeConfig()

console.log('Runtime config:', config)
if (import.meta.server) {
  console.log('API secret:', config.apiSecret)
}
</script>

<template>
  <div>
    <div>Смотрите консоль разработчика!</div>
  </div>
</template>
Безопасность: не выводите на клиент ключи runtime config и не передавайте их в useState.

Плагины

В пользовательском плагине используйте useRuntimeConfig() внутри defineNuxtPlugin.

app/plugins/config.ts
export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()

  console.log('API base URL:', config.public.apiBase)
})

Серверные маршруты

В серверных маршрутах runtime config доступен через useRuntimeConfig.

server/api/test.ts
export default defineEventHandler(async (event) => {
  const { apiSecret } = useRuntimeConfig()
  const result = await $fetch('https://my.api.com/test', {
    headers: {
      Authorization: `Bearer ${apiSecret}`,
    },
  })
  return result
})
Передавать event в useRuntimeConfig необязательно, но рекомендуется — так для серверных маршрутов учитывается переопределение runtime config переменными окружения в рантайме.

Типизация runtime config

Nuxt старается автоматически сгенерировать интерфейс TypeScript из заданного runtime config с помощью unjs/untyped.

Типы можно задать вручную:

index.d.ts
declare module 'nuxt/schema' {
  interface RuntimeConfig {
    apiSecret: string
  }
  interface PublicRuntimeConfig {
    apiBase: string
  }
}
// При расширении типов важно импортировать/экспортировать хотя бы что-то
export {}
nuxt/schema — удобный модуль для доступа к схеме Nuxt в проекте. Авторам модулей лучше расширять @nuxt/schema.