Что такое nuxt.config.ts и какие параметры конфигурации наиболее важны?

Что такое nuxt.config.ts

nuxt.config.ts — TypeScript-файл конфигурации, экспортирующий объект через defineNuxtConfig(). Nuxt читает его при старте dev-сервера и при сборке. Файл типизирован: IDE подсказывает все допустимые поля.

Наиболее важные параметры

• runtimeConfig — переменные окружения, доступные на сервере (runtimeConfig.secretKey) и на клиенте (runtimeConfig.public.*). Значения переопределяются через env-переменные вида NUXT_SECRET_KEY.
• modules — список Nuxt-модулей: @pinia/nuxt, @nuxtjs/tailwindcss, @nuxt/image и т.д.
• routeRules — правила рендеринга для конкретных маршрутов: ssr, prerender, redirect, headers.
• nitro — настройки Nitro-сервера: preset (node, vercel, cloudflare-workers и др.), storage, plugins.
• app — глобальные мета-теги (head), базовый URL (baseURL), pageTransition.
• vite / webpack — передача настроек сборщику: алиасы, плагины, оптимизация.
• typescript — strict: true, shim: false.
• experimental — экспериментальные флаги: payloadExtraction, typedPages.

Пример конфигурации

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@pinia/nuxt',
    '@nuxtjs/tailwindcss',
    '@nuxt/image',
  ],

  runtimeConfig: {
    // Только на сервере
    databaseUrl: process.env.DATABASE_URL,
    // На клиенте и сервере
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE ?? '/api',
      appName: 'MyApp',
    },
  },

  routeRules: {
    // Статическая генерация главной
    '/': { prerender: true },
    // ISR каждые 60 секунд
    '/blog/**': { isr: 60 },
    // Только SPA
    '/dashboard/**': { ssr: false },
    // Редирект
    '/old-path': { redirect: '/new-path' },
  },

  nitro: {
    preset: 'node-server',
    storage: {
      redis: {
        driver: 'redis',
        url: process.env.REDIS_URL,
      },
    },
  },

  app: {
    head: {
      title: 'MyApp',
      meta: [{ name: 'description', content: 'My Nuxt 3 app' }],
      link: [{ rel: 'icon', href: '/favicon.ico' }],
    },
    pageTransition: { name: 'page', mode: 'out-in' },
  },

  typescript: {
    strict: true,
  },

  experimental: {
    typedPages: true,
  },
});

routeRules подробнее

Гибридный рендеринг Nuxt 3 позволяет задавать разный режим для каждого маршрута в одном приложении:

• { ssr: false } — клиентский SPA
• { prerender: true } — полная статика
• { isr: N } — Incremental Static Regeneration каждые N секунд
• { cache: { maxAge: 3600 } } — кэширование ответов Nitro

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

• runtimeConfig vs env: значения из defineNuxtConfig — дефолты. Реальные секреты должны приходить из env-переменных, иначе они попадут в бандл.
• public.* попадает в клиентский JS-бандл — никогда не кладите туда токены или ключи API.
• modules порядок важен: некоторые модули (например @nuxtjs/i18n) должны идти до других или после — читайте их документацию.
• nitro.preset: если не указан явно, Nuxt выбирает node-server. При деплое на Vercel/Cloudflare нужно задавать пресет явно, иначе сборка может не работать.
• vite.optimizeDeps: некоторые ESM-пакеты требуют включения в optimizeDeps.include, иначе дают ошибки при SSR.
• typescript.shim: при shim: false не генерируются *.d.ts файлы для .vue-компонентов — нужно убедиться, что IDE поддерживает Volar.
• experimental флаги могут ломаться между минорными версиями Nuxt — следите за changelog.
• app.head vs useHead(): глобальный app.head не реактивен; для динамических мета-тегов используйте useHead() или useSeoMeta() в компонентах.

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

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