Плагины, компоненты и другое

Внедрение плагинов, компонентов, композаблов и серверных маршрутов из модуля.

Типичные приёмы при разработке модулей.

Изменение конфигурации Nuxt

Модули могут читать и менять конфигурацию Nuxt. Пример — включение экспериментальной возможности:

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    nuxt.options.experimental ||= {}
    nuxt.options.experimental.componentIslands = true
  },
})

Для более сложного слияния конфигурации используйте defu.

Видео Vue School об изменении конфигурации Nuxt.

Проброс опций в runtime

Модули не входят в runtime приложения, поэтому их опции там по умолчанию недоступны. Часто часть опций нужна в runtime — рекомендуем прокидывать их через runtimeConfig Nuxt.

import { defineNuxtModule } from '@nuxt/kit'
import { defu } from 'defu'

export default defineNuxtModule({
  setup (options, nuxt) {
    nuxt.options.runtimeConfig.public.myModule = defu(nuxt.options.runtimeConfig.public.myModule, {
      foo: options.foo,
    })
  },
})

defu расширяет публичный runtime-конфиг пользователя, а не перезаписывает его.

Доступ к опциям модуля в плагине, компоненте или приложении — как к любому runtime-конфигу:

import { useRuntimeConfig } from '@nuxt/kit'

const options = useRuntimeConfig().public.myModule
Не помещайте в публичный runtime-конфиг чувствительные данные (API-ключи и т.п.) — они попадут в публичный бандл.
Узнать больше Docs > 4 X > Guide > Going Further > Runtime Config.
Видео Vue School о передаче и пробросе опций модуля.

Добавление плагинов

Плагины — распространённый способ добавить runtime-логику. Регистрировать их из модуля можно через утилиту addPlugin.

import { addPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addPlugin(resolver.resolve('./runtime/plugin'))
  },
})
Узнать больше Docs > 4 X > Guide > Going Further > Kit.

Добавление компонентов

Если модуль поставляет Vue-компоненты, используйте addComponent для их автоимпорта в Nuxt.

import { addComponent, createResolver, defineNuxtModule, useRuntimeConfig } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addComponent({
      name: 'MySuperComponent',
      export: 'MySuperComponent',
      filePath: resolver.resolve('runtime/app/components/MySuperComponent.vue'),
    })

    addComponent({
      name: 'MyAwesomeComponent',
      export: 'MyAwesomeComponent',
      filePath: '@vue/awesome-components',
    })
  },
})

Либо добавьте целую директорию через addComponentsDir:

import { addComponentsDir, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addComponentsDir({
      path: resolver.resolve('runtime/app/components'),
    })
  },
})
Рекомендуется префикс для экспортов, чтобы не конфликтовать с кодом пользователя и другими модулями.
Узнать больше Docs > 4 X > Guide > Modules > Best Practices#prefix Your Exports.
Компоненты, страницы, композаблы и прочие файлы, которые в приложении лежали бы в app/, в модуле должны быть в runtime/app/ для корректной проверки типов.

Добавление композаблов

Для композаблов используйте addImports — Nuxt подхватит их как автоимпорты.

import { addImports, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addImports({
      name: 'useComposable',
      as: 'useMyComposable',
      from: resolver.resolve('runtime/app/composables/useComposable'),
    })
  },
})

Несколько записей — массивом; целая директория — через addImportsDir. Рекомендуется префикс экспортов. Файлы для app-контекста — в runtime/app/.

Keyed-функции

Для согласованности состояния между сервером и клиентом (как useState или useAsyncData) можно зарегистрировать функцию в keyedComposables: компилятор Nuxt будет подставлять уникальный ключ. Подробности и ограничения — в документации.

Добавление серверных маршрутов

import { addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addServerHandler({
      route: '/api/_my-module/hello',
      handler: resolver.resolve('./runtime/server/api/hello/index.get'),
    })

    addServerHandler({
      route: '/api/_my-module/hello/:name',
      handler: resolver.resolve('./runtime/server/api/hello/[name].get'),
    })
  },
})

Рекомендуется префикс серверных маршрутов (например /api/_foo/...).

Узнать больше Docs > 4 X > Guide > Modules > Best Practices#prefix Your Exports.

Другие ресурсы

Стили и прочие ассеты можно подключать через nuxt.options.css или хук Nitro publicAssets. Зависимости от других модулей задавайте через moduleDependencies с версиями и слиянием конфигурации.

Опция moduleDependencies заменяет устаревший installModule и обеспечивает правильный порядок установки и слияние конфигурации.