mirror of
https://github.com/nuxt/nuxt.git
synced 2024-12-02 10:27:15 +00:00
126 lines
2.9 KiB
Markdown
126 lines
2.9 KiB
Markdown
---
|
|
icon: IconDirectory
|
|
title: 'plugins'
|
|
head.title: Plugins directory
|
|
---
|
|
|
|
# Plugins directory
|
|
|
|
Nuxt will automatically read the files in your `plugins` directory and load them. You can use `.server` or `.client` suffix in the file name to load a plugin only on the server or client side.
|
|
|
|
::alert{type=warning}
|
|
All plugins in your `plugins/` directory are auto-registered, so you should not add them to your `nuxt.config` separately.
|
|
::
|
|
|
|
## Which files are registered
|
|
|
|
Only files at the top level of the `plugins/` directory (or index files within any subdirectories) will be registered as plugins.
|
|
|
|
For example:
|
|
|
|
```bash
|
|
plugins
|
|
| - myPlugin.ts
|
|
| - myOtherPlugin
|
|
| --- supportingFile.ts
|
|
| --- componentToRegister.vue
|
|
| --- index.ts
|
|
```
|
|
|
|
Only `myPlugin.ts` and `myOtherPlugin/index.ts` would be registered.
|
|
|
|
## Creating plugins
|
|
|
|
The only argument passed to a plugin is [`nuxtApp`](/api/composables/use-nuxt-app).
|
|
|
|
```ts
|
|
export default defineNuxtPlugin(nuxtApp => {
|
|
// Doing something with nuxtApp
|
|
})
|
|
```
|
|
|
|
## Automatically providing helpers
|
|
|
|
If you would like to provide a helper on the `NuxtApp` instance, return it from the plugin under a `provide` key. For example:
|
|
|
|
```ts
|
|
export default defineNuxtPlugin(() => {
|
|
return {
|
|
provide: {
|
|
hello: (msg: string) => `Hello ${msg}!`
|
|
}
|
|
}
|
|
})
|
|
```
|
|
|
|
In another file you can use this:
|
|
|
|
```vue
|
|
<template>
|
|
<div>
|
|
{{ $hello('world') }}
|
|
</div>
|
|
</template>
|
|
|
|
<script setup lang="ts">
|
|
// alternatively, you can also use it here
|
|
const { $hello } = useNuxtApp()
|
|
</script>
|
|
```
|
|
|
|
## Typing plugins
|
|
|
|
If you return your helpers from the plugin, they will be typed automatically; you'll find them typed for the return of `useNuxtApp()` and within your templates.
|
|
|
|
::alert
|
|
If you need to use a provided helper _within_ another plugin, you can call `useNuxtApp()` to get the typed version. But in general, this should be avoided unless you are certain of the plugins' order.
|
|
::
|
|
|
|
### Advanced
|
|
|
|
For advanced use-cases, you can declare the type of injected properties like this:
|
|
|
|
```ts [index.d.ts]
|
|
declare module '#app' {
|
|
interface NuxtApp {
|
|
$hello (msg: string): string
|
|
}
|
|
}
|
|
|
|
declare module '@vue/runtime-core' {
|
|
interface ComponentCustomProperties {
|
|
$hello (msg: string): string
|
|
}
|
|
}
|
|
|
|
export { }
|
|
```
|
|
|
|
## Vue plugins
|
|
|
|
If you want to use Vue plugins, like [vue-gtag](https://github.com/MatteoGabriele/vue-gtag) to add Google Analytics tags, you can use a Nuxt plugin to do so.
|
|
|
|
> There is an Open RFC to make this even easier! See [nuxt/framework#1175](https://github.com/nuxt/framework/discussions/1175)
|
|
|
|
First, install the plugin you want.
|
|
|
|
```bash
|
|
yarn add --dev vue-gtag-next
|
|
```
|
|
|
|
Then create a plugin file `plugins/vue-gtag.client.js`.
|
|
|
|
```ts
|
|
import VueGtag from 'vue-gtag-next'
|
|
|
|
export default defineNuxtPlugin((nuxtApp) => {
|
|
nuxtApp.vueApp.use(VueGtag, {
|
|
property: {
|
|
id: 'GA_MEASUREMENT_ID'
|
|
}
|
|
})
|
|
})
|
|
```
|
|
|
|
:LinkExample{link="/examples/app/plugins"}
|