Плагины

Исходный код
Nuxt Kit предоставляет утилиты для подключения плагинов и шаблонов плагинов из модулей.

Плагины — обособленный код, который обычно расширяет Vue на уровне приложения. В Nuxt файлы из каталога plugins/ подключаются автоматически; чтобы поставлять плагин вместе с модулем, используйте addPlugin и addPluginTemplate — с контролем режима (client/server), порядка выполнения и т.д.

addPlugin

Регистрирует плагин Nuxt и добавляет его в общий список плагинов.

Смотрите видео от Vue School о методе addPlugin.

Использование

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

export default defineNuxtModule({
  setup () {
    const { resolve } = createResolver(import.meta.url)

    addPlugin({
      src: resolve('runtime/plugin.js'),
      mode: 'client',
    })
  },
})

Тип

function addPlugin (plugin: NuxtPlugin | string, options?: AddPluginOptions): NuxtPlugin

Параметры

plugin: объект плагина или строка с путём к файлу. Строка превращается в объект с полем src.

У объекта плагина обычно есть поля:

СвойствоТипОбязательноОписание
srcstringtrueПуть к файлу плагина.
mode'all' | 'server' | 'client'false'all' — клиент и сервер; 'server' / 'client' — только соответствующий бандл. Модификаторы .client/.server в имени src задают то же самое.
ordernumberfalseПорядок выполнения: меньшее значение — раньше (у пользовательских плагинов по умолчанию 0). Ориентиры: «ранние» плагины ≈ -20, «поздние» ≈ 20. Задавайте только при необходимости.
Не задавайте order без нужды: чтобы выполнить код после встроенных плагинов, чаще достаточно append: true.

options: необязательный объект со свойствами:

СвойствоТипОбязательноОписание
appendbooleanfalseПри true плагин добавляется в конец списка, при false — в начало. По умолчанию false.

Примеры

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

export default defineNuxtModule({
  setup () {
    const { resolve } = createResolver(import.meta.url)

    addPlugin({
      src: resolve('runtime/plugin.js'),
      mode: 'client',
    })
  },
})

addPluginTemplate

Добавляет шаблон и регистрирует его как плагин Nuxt. Нужно, когда исходный код плагина должен собираться на этапе билда.

Смотрите видео от Vue School о методе addPluginTemplate.

Использование

import { addPluginTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options) {
    addPluginTemplate({
      filename: 'module-plugin.mjs',
      getContents: () => `import { defineNuxtPlugin } from '#app/nuxt'
export default defineNuxtPlugin({
  name: 'module-plugin',
  setup (nuxtApp) {
    ${options.log ? 'console.log("Установка плагина")' : ''}
  }
})`,
    })
  },
})

Тип

function addPluginTemplate (pluginOptions: NuxtPluginTemplate, options?: AddPluginOptions): NuxtPlugin

Параметры

pluginOptions: объект шаблона плагина со свойствами:

СвойствоТипОбязательноОписание
srcstringfalseПуть к шаблону. Если src не задан, вместо него нужно указать getContents.
filenamestringfalseИмя файла шаблона. Если filename не задан, оно выводится из пути src; тогда опция src обязательна.
dststringfalseПуть к целевому файлу. Если dst не задан, он формируется из filename и опции Nuxt buildDir.
mode'all' | 'server' | 'client'false'all' — клиент и сервер; 'server' / 'client' — только соответствующий бандл. Модификаторы .client/.server в src задают то же.
optionsRecord<string, any>falseОпции, передаваемые в шаблон.
getContents(data: Record<string, any>) => string | Promise<string>falseФункция с объектом options; возвращает строку или промис со строкой. Если задан src, эта функция игнорируется.
writebooleanfalseПри true шаблон записывается в целевой файл; иначе используется только виртуальная файловая система.
ordernumberfalseПорядок выполнения плагина (как у addPlugin). Меньше — раньше; по умолчанию 0. Ориентиры ≈ -20 / 20 — только для нетривиальных случаев.
Для динамической генерации кода плагина используйте getContents. Параметр order задавайте только при явной необходимости.

options: необязательный объект со свойствами:

СвойствоТипОбязательноОписание
appendbooleanfalseПри true плагин добавляется в конец списка, при false — в начало. По умолчанию false.

Примеры

Генерация шаблона плагина с разными опциями

addPluginTemplate уместен, если тело плагина должно зависеть от опций модуля или других данных сборки. Внутри Nuxt эта функция, в частности, участвует в настройке экземпляра Vue.

module.ts
import { addPluginTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (_, nuxt) {
    if (nuxt.options.vue.config && Object.values(nuxt.options.vue.config).some(v => v !== null && v !== undefined)) {
      addPluginTemplate({
        filename: 'vue-app-config.mjs',
        write: true,
        getContents: () => `import { defineNuxtPlugin } from '#app/nuxt'
export default defineNuxtPlugin({
  name: 'nuxt:vue-app-config',
  enforce: 'pre',
  setup (nuxtApp) {
    ${Object.keys(nuxt.options.vue.config!)
        .map(k => `nuxtApp.vueApp.config[${JSON.stringify(k)}] = ${JSON.stringify(nuxt.options.vue.config![k as 'idPrefix'])}`)
        .join('\n')
    }
  }
})`,
      })
    }
  },
})

В зависимости от nuxt.config получается разный сгенерированный код.

export default defineNuxtConfig({
  vue: {
    config: {
      idPrefix: 'nuxt',
    },
  },
})

Шаблон EJS для генерации плагина

Допустим шаблон EJS: объект options передаётся в шаблон при генерации кода плагина.

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

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

    addPluginTemplate({
      src: resolve('templates/plugin.ejs'),
      filename: 'plugin.mjs',
      options: {
        ssr: nuxt.options.ssr,
      },
    })
  },
})
При compatibilityVersion: 4 Nuxt по умолчанию не компилирует шаблоны через lodash.template. Старое поведение можно включить через experimental.compileTemplate, но поддержка EJS будет удалена в следующей мажорной версии.