Nuxt Layers: модульная архитектура для больших проектов

Введение

Когда проект становится крупным, классическая структура “всё в одном” начинает мешать: конфиги разрастаются, компоненты и утилиты перемешиваются, повторное использование становится болью. В Nuxt 4 появилась мощная возможность — Layers (слои).

Слои позволяют разделять код на независимые модули: конфигурации, темы, UI-библиотеки, бизнес-фичи. Это упрощает масштабирование, повторное использование и делает архитектуру чище.

Что такое Nuxt Layers

Nuxt Layer — это почти полноценное Nuxt-приложение: у него может быть свой nuxt.config.ts, компоненты, страницы, плагины, API и т.д. Разница лишь в том, что слой “расширяет” другое приложение.

Зачем это нужно:

• выносить общую логику, конфиги и хуки;
• подключать готовые темы и UI-компоненты;
• переиспользовать бизнес-фичи между проектами;
• собирать приложение из модулей как конструктор.

Как подключать слои

Локальные слои

Если в проекте есть папка layers, Nuxt автоматически регистрирует её содержимое. У каждого слоя появляется алиас вида:

#layers/<имя_слоя>/

Пример:

layers/
 └── ui/
     ├── components/
     └── nuxt.config.ts

Теперь компоненты и конфигурации из слоя ui доступны всему проекту.

Внешние слои через extends

Чтобы подключить слой из npm или GitHub, в nuxt.config.ts используется опция extends:

export default defineNuxtConfig({
  extends: [
    '../base',                        // локальный слой
    '@my-themes/awesome',             // npm-пакет
    'github:my-themes/awesome#v1',    // GitHub-репозиторий
  ],
})

Можно даже переименовывать слой через meta.name.

Приоритет слоёв

Важно помнить, что несколько слоёв могут содержать одинаковые файлы. Кто победит?

1. Слои из extends (в порядке записи).
2. Локальные layers/ (сортируются по алфавиту).
3. Сам проект (всегда имеет приоритет).

То есть, если слой и проект определяют один и тот же компонент, возьмётся версия из проекта.

Примеры использования

Общая конфигурация

Выносите модули, плагины и настройки в слой base-config, чтобы не дублировать их в десятках проектов.

// layers/base-config/nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@vueuse/nuxt'],
  css: ['~/assets/main.css'],
})

И подключаете через extends.

Темы и стили

Создайте слой theme-dark или theme-corporate, где будут храниться стили и компоненты. В разных проектах можно просто подключать нужную тему.

Фичи как слои

Разделяйте проект на бизнес-фичи: billing, auth, profile. Каждый слой содержит страницы, API, хуки и компоненты. Основное приложение лишь “собирает” их.

Как устроен слой

Структура слоя ничем не отличается от обычного приложения Nuxt:

nuxt.config.ts
app.config.ts
components/
layouts/
pages/
composables/
plugins/
server/

Можно даже запускать слой отдельно через папку playground/ для тестов.

Советы по работе со слоями

1. Не злоупотребляйте — много слоёв усложняют архитектуру.
2. Держите ответственность отдельной — слой = одна цель (UI, тема, фича).
3. Следите за зависимостями — иногда пакеты нужно установить и в проект.
4. Версионируйте — используйте semver и теги в Git.
5. Тестируйте отдельно — playground или автотесты помогут.
6. Документируйте API слоя — какие компоненты и хуки он экспортирует.

Заключение

Nuxt Layers — это фундамент для модульной архитектуры. С их помощью можно:

• переиспользовать код между проектами,
• выделять темы и общие конфиги,
• собирать приложения как конструктор из фич.

Этот подход делает проекты гибкими, поддерживаемыми и масштабируемыми.

Если раньше у вас был “монолит” на Nuxt, теперь есть шанс превратить его в удобный набор переиспользуемых модулей.