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

Как устроены модули Nuxt и как их описывать.

Есть два вида модулей:

Принцип работы одинаковый.

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

В стартере точка входа — src/module.ts.

Определение модуля — то, что 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}`)
  })
})

Такой низкоуровневый вид не рекомендуем. Для публикации в npm лучше объектный синтаксис с meta.

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

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    // Обычно имя npm-пакета модуля
    name: '@nuxtjs/example',
    // Ключ в `nuxt.config`, где хранятся опции модуля
    configKey: 'sample',
    // Ограничения совместимости
    compatibility: {
      // Semver-диапазон поддерживаемых версий Nuxt
      nuxt: '>=3.0.0',
    },
  },
  // Дефолтные опции модуля; можно задать функцией, возвращающей объект
  defaults: {},
  // Краткая запись для регистрации хуков Nuxt
  hooks: {},
  // Настройка других модулей: не гарантирует, что они выполнятся до вашего,
  // но позволяет изменить их конфигурацию до их запуска
  moduleDependencies: {
    'some-module': {
      // Semver-диапазон для пакета `some-module`; несовпадение с установленной версией — ошибка при старте Nuxt
      version: '>=2',
      // По умолчанию записи `moduleDependencies` попадают в список модулей к установке Nuxt,
      // если не указано `optional`
      optional: true,
      // Конфигурация, полностью перебивающая `nuxt.options`
      overrides: {},
      // Значения по умолчанию: перебивают дефолты модуля, но не заданное пользователем в `nuxt.options`
      defaults: {},
    },
  },
  // Логика модуля; может быть асинхронной
  setup (moduleOptions, nuxt) {
    // ...
  },
})

defineNuxtModule возвращает обёртку с сигнатурой (inlineOptions, nuxt). Перед setup она:

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

Код рантайма

В стартере каталог рантайма — src/runtime/.

Сама конфигурация модуля в рантайм приложения не попадает. Чтобы добавить код в приложение пользователя, используйте каталог runtime (код времени выполнения).

Туда можно положить всё, что относится к Nuxt-приложению:

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

  • API-маршруты
  • промежуточное ПО сервера (server middleware)
  • плагины Nitro

И любые другие артефакты (стили, медиа и т.д.), которые модуль «впрыскивает» в проект.

Подключение — из определения модуля.

Про внедрение ресурсов — в рецептах.
В опубликованных модулях автоимпорты из каталога рантайма не работают — импортируйте явно из #imports и т.п.

Автоимпорт для файлов в node_modules отключён из соображений производительности.