Nuxt/docs/content/3.docs/2.directory-structure/11.plugins.md

124 lines
2.8 KiB
Markdown
Raw Normal View History

---
icon: IconDirectory
title: 'plugins'
head.title: Plugins directory
---
# Plugins directory
2021-11-21 12:31:44 +00:00
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
2021-10-15 10:14:17 +00:00
The only argument passed to a plugin is [`nuxtApp`](/docs/usage/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: () => 'world'
}
}
})
```
In another file you can use this:
```vue
<template>
<div>
{{ $hello() }}
</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
2021-11-21 12:31:44 +00:00
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
2021-11-21 12:31:44 +00:00
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) => {
2021-10-22 10:11:37 +00:00
nuxtApp.vueApp.use(VueGtag, {
property: {
id: 'GA_MEASUREMENT_ID'
}
})
})
```