Nuxt/docs/3.api/5.kit/9.plugins.md

title	description	links
Plugins	Nuxt Kit provides a set of utilities to help you create and use plugins. You can add plugins or plugin templates to your module using these functions.	label icon to size Source i-simple-icons-github https://github.com/nuxt/nuxt/blob/main/packages/kit/src/plugin.ts xs

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).

::callout{color="amber" icon="i-ph-warning-duotone"} 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

::code-group

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

// https://github.com/nuxt/nuxters
export default defineNuxtPlugin((nuxtApp) => {
  const colorMode = useColorMode()

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

::

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).

::callout{color="amber" icon="i-ph-warning-duotone"} 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

::code-group

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

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

export default defineNuxtPlugin((nuxtApp) => {
  const firebaseApp = nuxtApp.$firebaseApp

  nuxtApp.vueApp.use(VueFire, { firebaseApp })

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

::