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.

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:

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.

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:

export default defineNuxtPlugin(() => {
  return {
    provide: {
      hello: () => 'world'
    }
  }
})

In another file you can use this:

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

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:

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

First, install the plugin you want.

yarn add --dev vue-gtag-next

Then create a plugin file plugins/vue-gtag.client.js.

import VueGtag from 'vue-gtag-next'
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(VueGtag, {
    property: {
      id: 'GA_MEASUREMENT_ID'
    }
  })
})

🔎

Read and edit a live example in Examples > App > Plugins