Plugins

Plugins are self-contained code that usually add app-level functionality to Vue. In Nuxt, plugins are automatically imported from the app/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 adds it to the plugins array.

::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/injecting-plugins?friend=nuxt" target="_blank"} Watch Vue School video about addPlugin. ::

Usage#

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

}, })

### Type

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

Parameters#

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:

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

options: Optional object with the following properties:

Example#

::code-group

```ts [module.ts] 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',
})

}, })

```ts [runtime/plugin.ts]
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.

::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/injecting-plugin-templates?friend=nuxt" target="_blank"} Watch Vue School video about addPluginTemplate. ::

Usage#

```ts twoslash 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")' : ''} } }), }) }, })

### Type

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

Parameters#

pluginOptions: A plugin template object with the following properties:

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

options: Optional object with the following properties:

Example#

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.

```ts twoslash [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.

::code-group

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  vue: {
    config: {
      idPrefix: 'nuxt',
    },
  },
})

```ts [#build/vue-app-config.mjs] import { defineNuxtPlugin } from '#app/nuxt'

export default defineNuxtPlugin({ name: 'nuxt:vue-app-config', enforce: 'pre', setup (nuxtApp) { nuxtApp.vueApp.config.idPrefix = 'nuxt' }, }) ```

::