Plugins

Plugins are self-contained code that usually add app-level functionality to Vue. In Nuxt, plugins are automatically imported from the plugins directory. However, if you need to ship a plugin with your module, Nuxt Kit provides the addPlugin and addPluginTemplate methods. These utils allow you to customize the plugin configuration to better suit your needs.

`addPlugin`

Registers a Nuxt plugin and to the plugins array.

Type

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

interface NuxtPlugin {
  src: string
  mode?: 'all' | 'server' | 'client'
  order?: number
}

interface AddPluginOptions { append?: boolean }

Parameters

`plugin`

Type: NuxtPlugin | string

Required: true

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:

src (required)
Type: string
Path to the plugin.
mode (optional)
Type: 'all' | 'server' | 'client'
Default: 'all'
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 (optional)
Type: number
Default: 0
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).

Don't use order unless you know what you're doing. For most plugins, the default order of 0 is sufficient. To append a plugin to the end of the plugins array, use the append option instead.

`options`

Type: AddPluginOptions

Default: {}

Options to pass to the plugin. If append is set to true, the plugin will be appended to the plugins array instead of prepended.

Examples

module.ts

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

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

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

`addPluginTemplate`

Adds a template and registers as a nuxt plugin. This is useful for plugins that need to generate code at build time.

Type

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

interface NuxtPluginTemplate<Options = Record<string, any>> {
  src?: string,
  filename?: string,
  dst?: string,
  mode?: 'all' | 'server' | 'client',
  options?: Options,
  getContents?: (data: Options) => string | Promise<string>,
  write?: boolean,
  order?: number
}

interface AddPluginOptions { append?: boolean }

interface NuxtPlugin {
  src: string
  mode?: 'all' | 'server' | 'client'
  order?: number
}

Parameters

`pluginOptions`

Type: NuxtPluginTemplate

Required: true

A plugin template object with the following properties:

src (optional)
Type: string
Path to the template. If src is not provided, getContents must be provided instead.
filename (optional)
Type: string
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 (optional)
Type: string
Path to the destination file. If dst is not provided, it will be generated from the filename path and nuxt buildDir option.
mode (optional)
Type: 'all' | 'server' | 'client'
Default: 'all'
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 (optional)
Type: Options
Options to pass to the template.
getContents (optional)
Type: (data: Options) => string | Promise<string>
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 (optional)
Type: boolean
If set to true, the template will be written to the destination file. Otherwise, the template will be used only in virtual filesystem.
order (optional)
Type: number
Default: 0
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).

Don't use order unless you know what you're doing. For most plugins, the default order of 0 is sufficient. To append a plugin to the end of the plugins array, use the append option instead.

`options`

Type: AddPluginOptions

Default: {}

Options to pass to the plugin. If append is set to true, the plugin will be appended to the plugins array instead of prepended.

Examples

module.ts

// https://github.com/vuejs/vuefire
import { createResolver, defineNuxtModule, addPluginTemplate } from '@nuxt/kit'

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

    addPluginTemplate({
      src: resolve(templatesDir, 'plugin.ejs'),
      options: {
        ...options,
        ssr: nuxt.options.ssr,
      },
    })
  }
})