Что такое useRuntimeConfig() и как он используется на сервере и на клиенте?

Что такое useRuntimeConfig

useRuntimeConfig() — composable Nuxt, предоставляющий доступ к переменным из блока runtimeConfig в nuxt.config.ts. Главная особенность: переменные можно переопределить через переменные окружения без пересборки приложения.

Определение конфигурации

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // Только серверная часть (НИКОГДА не попадает в клиентский JS)
    databaseUrl: process.env.DATABASE_URL ?? 'postgres://localhost/mydb',
    jwtSecret: process.env.JWT_SECRET ?? 'fallback-secret',
    stripeSecretKey: '',  // Пустая строка — обязательный env

    // Публичная часть — доступна везде
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE ?? '/api',
      appName: 'MyApp',
      analyticsId: '',
    },
  },
});

Маппинг переменных окружения

Nuxt автоматически маппит env-переменные по правилу camelCase → SCREAMING_SNAKE_CASE с префиксом NUXT_:

• jwtSecret → NUXT_JWT_SECRET
• public.apiBase → NUXT_PUBLIC_API_BASE
• stripeSecretKey → NUXT_STRIPE_SECRET_KEY

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

// server/api/auth/login.post.ts
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig(event);  // передаём event для server-контекста
  const body = await readBody(event);

  // Используем серверный секрет
  const token = signJWT(body.userId, config.jwtSecret);

  // Используем публичный параметр
  const baseUrl = config.public.apiBase;

  return { token, baseUrl };
});

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

// components/ApiStatus.vue
<script setup lang="ts">
const config = useRuntimeConfig();
// config.public.apiBase — доступно
// config.jwtSecret — undefined (на клиенте серверные ключи скрыты)
console.log(config.public.apiBase);  // '/api'
</script>

Использование в серверных middleware

// server/middleware/auth.ts
export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event);
  const token = getHeader(event, 'Authorization')?.replace('Bearer ', '');
  if (token) {
    event.context.user = verifyJWT(token, config.jwtSecret);
  }
});

Файл .env для разработки

# .env (в .gitignore!)
NUXT_JWT_SECRET=super-secret-dev
NUXT_STRIPE_SECRET_KEY=sk_test_xxx
NUXT_PUBLIC_API_BASE=http://localhost:3001/api

Подводные камни

• public.* в клиентском бандле: всё что в public уходит в JS-файл страницы. Никаких секретов — только публичные URL, feature flags, названия.
• Нельзя добавлять ключи только через env: если ключа нет в nuxt.config.ts, NUXT_MY_VAR не будет доступен через useRuntimeConfig(). Нужно объявить его с пустым дефолтом.
• useRuntimeConfig вне контекста Nuxt: вызов в обычном .ts-файле вне composable/plugin/server-route бросит ошибку. Передавайте конфиг как параметр.
• process.env в nuxt.config: значения, заданные через process.env прямо в nuxt.config.ts, жёстко вшиваются в сборку. Для гибкого переопределения используйте пустую строку и env-маппинг.
• Серверный useRuntimeConfig(event): в Nitro-хэндлерах рекомендуется передавать event для правильного контекста; вызов без аргумента тоже работает, но считается менее явным.

• Путать useRuntimeConfig с похожим API из соседнего фреймворка.
• Не объяснять, где код выполняется: сервер, клиент, build step или runtime.
• Игнорировать влияние на hydration, cache, bundle size или безопасность.

• Точно объясняет назначение механизма «useRuntimeConfig».
• Показывает корректный минимальный пример без выдуманных API.
• Называет ограничения, failure modes и production-компромиссы.