Что такое Nuxt layers и как использовать их для компоновки проекта?

Nuxt Layers: компоновка проектов

Nuxt Layers — механизм расширения и переиспользования конфигурации, компонентов, composables, страниц и утилит между несколькими Nuxt-приложениями. Слой (layer) — это обычный Nuxt-проект или директория, которую другой проект подключает через extends в nuxt.config.ts.

Структура слоя

Слой может содержать любой подмножество стандартной файловой структуры Nuxt:

my-layer/
  components/
    Button.vue
    Modal.vue
  composables/
    useAuth.ts
  layouts/
    default.vue
  pages/
    login.vue
  server/
    api/
      health.get.ts
  nuxt.config.ts
  package.json

Подключение слоёв

// nuxt.config.ts приложения
export default defineNuxtConfig({
  extends: [
    // Локальная директория
    '../shared-ui',
    // npm-пакет
    '@company/nuxt-auth-layer',
    // GitHub-репозиторий (через giget)
    'github:org/repo/layer-name#main'
  ]
});

Практический пример: монорепозиторий

Типичная структура для компании с несколькими продуктами:

apps/
  admin/          # Nuxt-приложение для администраторов
  customer/       # Nuxt-приложение для клиентов
layers/
  base/           # Общая конфигурация, типы, утилиты
  design-system/  # Компоненты UI
  auth/           # Логика аутентификации

// layers/auth/nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    jwtSecret: '',
    public: {
      authEnabled: true
    }
  },
  nitro: {
    experimental: {
      wasm: true
    }
  }
});

// apps/admin/nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    '../../layers/base',
    '../../layers/design-system',
    '../../layers/auth'
  ],
  // Конфигурация приложения переопределяет слои
  runtimeConfig: {
    public: {
      appName: 'Admin Panel'
    }
  }
});

Приоритет слияния

Конфигурации мёржатся по принципу «последний выигрывает»: конфигурация приложения имеет наивысший приоритет, затем слои в порядке их объявления в extends — последний в списке переопределяет предыдущие. Компоненты, composables и страницы из приложения перекрывают одноимённые из слоёв.

Слои как npm-пакеты

Для публикации слоя в npm нужно настроить package.json:

{
  "name": "@company/nuxt-design-system",
  "main": "./nuxt.config.ts",
  "exports": {
    ".": "./nuxt.config.ts"
  }
}

Потребитель устанавливает через npm install @company/nuxt-design-system и добавляет в extends. Nuxt автоматически сканирует компоненты, composables и server-routes из слоя.

Переопределение компонентов

Если в слое есть components/Button.vue, а в приложении — своя версия components/Button.vue, приложение автоматически перекроет слой. Это удобно для кастомизации базового дизайна.

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

• Слои резолвятся через c12 и unjs/giget — GitHub-слои требуют network-доступа при сборке, что ломает CI без кеша.
• Circular dependencies между слоями не обнаруживаются автоматически и приводят к непредсказуемому поведению при мёрже конфигураций.
• TypeScript-типы из слоёв не всегда автоматически резолвятся — нужно явно добавить пути в tsconfig.json приложения через references или paths.
• Алиасы ~/ и @/ в слое указывают на корень слоя, не приложения — это приводит к ошибкам при импортах внутри слоя если он публикуется отдельно.
• Страницы из слоёв добавляются к роутингу приложения автоматически — если не хотите этого, явно исключайте через hooks: { 'pages:extend' }.
• Порядок в extends важен: если два слоя экспортируют одноимённый composable, победит последний в списке — это неочевидно при рефакторинге.
• Dev-сервер не всегда горячо перезагружает изменения в локальных слоях — иногда требуется полный рестарт.

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

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