Плагины

Исходники

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

Плагины представляют собой самодостаточный код, который обычно добавляет во Vue функциональность на уровне приложения. В Nuxt плагины автоматически импортируются из директории plugins/. Однако, если вам необходимо поставлять плагин вместе со своим модулем, Nuxt Kit предоставляет методы addPlugin и addPluginTemplate. Эти утилиты позволяют настроить конфигурацию плагина для лучшего соответствия вашим потребностям.

`addPlugin`

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

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

Usage

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: A plugin object or a string with the path to the plugin. If a string is provided, it will be converted to a plugin object with src set to the string value.

If a plugin object is provided, it must have the following properties:

Property	Type	Required	Description
`src`	`string`	`true`	Path to the plugin file.
`mode`	`'all' \| 'server' \| 'client'`	`false`	If set to `'all'`, the plugin will be included in both client and server bundles. If set to `'server'`, the plugin will only be included in the server bundle. If set to `'client'`, the plugin will only be included in the client bundle. You can also use `.client` and `.server` modifiers when specifying `src` option to use plugin only in client or server side.
`order`	`number`	`false`	Order of the plugin. This allows more granular control over plugin order and should only be used by advanced users. Lower numbers run first, and user plugins default to `0`. It's recommended to set `order` to a number between `-20` for `pre`-plugins (plugins that run before Nuxt plugins) and `20` for `post`-plugins (plugins that run after Nuxt plugins).

Avoid using order unless necessary. Use append if you simply need to register plugins after Nuxt defaults.

options: Optional object with the following properties:

Property	Type	Required	Description
`append`	`boolean`	`false`	If `true`, the plugin will be appended to the plugins array. If `false`, it will be prepended. Defaults to `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',
    })
  },
})

export default defineNuxtPlugin((nuxtApp) => {
  const colorMode = useColorMode()

  nuxtApp.hook('app:mounted', () => {
    if (colorMode.preference !== 'dark') {
      colorMode.preference = 'dark'
    }
  })
})

`addPluginTemplate`

Добавляет шаблон и регистрирует его как плагин Nuxt. Это полезно для плагинов, которые должны генерировать код во время сборки.

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

Usage

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("Plugin install")' : ''}
  }
})`,
    })
  },
})

Тип

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

Параметры

pluginOptions: A plugin template object with the following properties:

Property	Type	Required	Description
`src`	`string`	`false`	Path to the template. If `src` is not provided, `getContents` must be provided instead.
`filename`	`string`	`false`	Filename of the template. If `filename` is not provided, it will be generated from the `src` path. In this case, the `src` option is required.
`dst`	`string`	`false`	Path to the destination file. If `dst` is not provided, it will be generated from the `filename` path and nuxt `buildDir` option.
`mode`	`'all' \| 'server' \| 'client'`	`false`	If set to `'all'`, the plugin will be included in both client and server bundles. If set to `'server'`, the plugin will only be included in the server bundle. If set to `'client'`, the plugin will only be included in the client bundle. You can also use `.client` and `.server` modifiers when specifying `src` option to use plugin only in client or server side.
`options`	`Record<string, any>`	`false`	Options to pass to the template.
`getContents`	`(data: Record<string, any>) => string \| Promise<string>`	`false`	A function that will be called with the `options` object. It should return a string or a promise that resolves to a string. If `src` is provided, this function will be ignored.
`write`	`boolean`	`false`	If set to `true`, the template will be written to the destination file. Otherwise, the template will be used only in virtual filesystem.
`order`	`number`	`false`	Order of the plugin. This allows more granular control over plugin order and should only be used by advanced users. Lower numbers run first, and user plugins default to `0`. It's recommended to set `order` to a number between `-20` for `pre`-plugins (plugins that run before Nuxt plugins) and `20` for `post`-plugins (plugins that run after Nuxt plugins).

Prefer using getContents for dynamic plugin generation. Avoid setting order unless necessary.

options: Optional object with the following properties:

Property	Type	Required	Description
`append`	`boolean`	`false`	If `true`, the plugin will be appended to the plugins array. If `false`, it will be prepended. Defaults to `false`.

Примеры

Generate a plugin template with different options

Use addPluginTemplate when you need to generate plugin code dynamically at build time. This allows you to generate different plugin contents based on the options passed to it. For example, Nuxt internally uses this function to generate Vue app configurations.

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')
    }
  }
})`,
      })
    }
  },
})

This generates different plugin code depending on the provided configuration.

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

import { defineNuxtPlugin } from '#app/nuxt'
export default defineNuxtPlugin({
  name: 'nuxt:vue-app-config',
  enforce: 'pre',
  setup (nuxtApp) {
    nuxtApp.vueApp.config["idPrefix"] = "nuxt"
  }
})

Using an EJS template to generate a plugin

You can also use an EJS template to generate your plugin. Options can be passed through the options property and then used within the EJS template to generate the plugin content.

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,
      },
    })
  },
})

import { VueFire, useSSRInitialState } from 'vuefire'
import { defineNuxtPlugin } from '#imports'

export default defineNuxtPlugin((nuxtApp) => {
  const firebaseApp = nuxtApp.$firebaseApp
  nuxtApp.vueApp.use(VueFire, { firebaseApp })

  <% if(options.ssr) { %>
  if (import.meta.server) {
    nuxtApp.payload.vuefire = useSSRInitialState(undefined, firebaseApp)
  } else if (nuxtApp.payload?.vuefire) {
    useSSRInitialState(nuxtApp.payload.vuefire, firebaseApp)
  }
  <% } %>
})

If you set compatibilityVersion to 4, Nuxt no longer uses lodash.template to compile templates by default. You can still enable it via the experimental.compileTemplate option, but support for EJS templates will be removed entirely in the next major version.

Был ли материал полезен?

Report an issue or Edit this page on GitHub

Лейаут

Nuxt Kit предоставляет набор утилит, которые помогают вам работать с лейаутами.

Хуки жизненного цикла

Nuxt предоставляет мощную систему хуков для расширения практически всех аспекты с их помощью.