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

256 lines
7.3 KiB
Markdown
Raw Normal View History

---
title: Plugins
description: 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.
links:
- label: Source
icon: i-simple-icons-github
to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/plugin.ts
size: 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
```ts
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
```ts [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'
})
}
})
```
```ts [runtime/plugin.js]
// 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
```ts
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
```ts [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'),
filename: 'plugin.mjs',
options: {
...options,
ssr: nuxt.options.ssr,
},
})
}
})
```
```ts [runtime/plugin.ejs]
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 (process.server) {
nuxtApp.payload.vuefire = useSSRInitialState(undefined, firebaseApp)
} else if (nuxtApp.payload?.vuefire) {
useSSRInitialState(nuxtApp.payload.vuefire, firebaseApp)
}
<% } %>
})
```
::