Структура модуля

Модули Nuxt бывают двух видов:

• опубликованные — распространяются через npm, часть сообщества перечислена на сайте Nuxt;
• локальные — находятся внутри проекта Nuxt: инлайн в nuxt.config или в директории modules.

В обоих случаях они работают одинаково.

Определение модуля

Определение модуля — точка входа: его загружает Nuxt, когда модуль указан в конфигурации.

На нижнем уровне определение модуля — простая (возможно асинхронная) функция с опциями пользователя и объектом nuxt для взаимодействия с Nuxt.

export default function (inlineOptions, nuxt) {
  // Любая логика...
  console.log(inlineOptions.token) // `123`
  console.log(nuxt.options.dev) // `true` или `false`
  nuxt.hook('ready', (nuxt) => {
    console.log('Nuxt готов')
  })
}

Подсказки типов даёт хелпер верхнего уровня defineNuxtModule из Nuxt Kit.

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule((options, nuxt) => {
  nuxt.hook('pages:extend', (pages) => {
    console.log(`Найдено ${pages.length} страниц`)
  })
})

Рекомендуется не использовать такую низкоуровневую функцию, а описывать модуль объектом с полем meta для идентификации, особенно при публикации в npm.

defineNuxtModule упрощает написание модулей, реализует типовые паттерны, обеспечивает совместимость и удобство для авторов и пользователей.

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: '@nuxtjs/example',        // обычно имя npm-пакета
    configKey: 'sample',            // ключ опций в nuxt.config
    compatibility: {
      nuxt: '>=3.0.0',              // поддерживаемые версии Nuxt
    },
  },
  defaults: {},
  hooks: {},
  moduleDependencies: {
    'some-module': {
      version: '>=2',
      optional: true,
      overrides: {},
      defaults: {},
    },
  },
  setup (moduleOptions, nuxt) {
    // ...
  },
})

defineNuxtModule возвращает обёртку с сигнатурой (inlineOptions, nuxt). Обёртка применяет defaults и другие шаги перед вызовом setup:

• поддержка defaults и meta.configKey для слияния опций;
• подсказки типов и вывод типов;
• установка модуля только один раз по ключу из meta.name или meta.configKey;
• автоматическая регистрация хуков Nuxt;
• проверка совместимости по meta;
• экспорт getOptions и getMeta для внутреннего использования;
• совместимость при использовании актуального @nuxt/kit;
• интеграция с инструментами сборки модулей.

Runtime-код

Модули, как и всё в конфигурации Nuxt, не входят в runtime приложения. Но модуль может поставлять или внедрять runtime-код в приложение — для этого служит директория runtime.

В runtime можно размещать ресурсы приложения Nuxt:

• компоненты Vue;
• композаблы;
• плагины Nuxt

Для серверного движка Nitro:

• API-маршруты;
• middleware;
• плагины Nitro

И любые другие ресурсы: стили, 3D-модели, изображения и т.д.

Внедрять эти ресурсы в приложение можно из определения модуля.