plugins/

Nuxt has a plugins system to use Vue plugins and more at the creation of your Vue application.

Nuxt automatically reads the files in the app/plugins/ directory and loads them at the creation of the Vue application.

All plugins inside are auto-registered, you don’t need to add them to your nuxt.config separately.

You can use .server or .client suffix in the file name to load a plugin only on the server or client side.

Registered Plugins

Only files at the top level of the directory (or index files within any subdirectories) will be auto-registered as plugins.

plugins/
  foo.ts      // scanned
  bar/
    baz.ts    // not scanned
    foz.vue   // not scanned
    index.ts  // currently scanned but deprecated

Only foo.ts and bar/index.ts would be registered.

To add plugins in subdirectories, you can use the app/plugins option in nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  plugins: [
    '~/plugins/bar/baz',
    '~/plugins/bar/foz',
  ],
})

Creating Plugins

The only argument passed to a plugin is nuxtApp.

plugins/hello.ts

export default defineNuxtPlugin((nuxtApp) => {
  // Doing something with nuxtApp
})

Object Syntax Plugins

It is also possible to define a plugin using an object syntax, for more advanced use cases. For example:

plugins/hello.ts

export default defineNuxtPlugin({
  name: 'my-plugin',
  enforce: 'pre', // or 'post'
  async setup (nuxtApp) {
    // this is the equivalent of a normal functional plugin
  },
  hooks: {
    // You can directly register Nuxt app runtime hooks here
    'app:created' () {
      const nuxtApp = useNuxtApp()
      // do something in the hook
    },
  },
  env: {
    // Set this value to `false` if you don't want the plugin to run when rendering server-only or island components.
    islands: true,
  },
})

If you are using the object-syntax, the properties are statically analyzed to produce a more optimized build. So you should not define them at runtime.

Registration Order

You can control the order in which plugins are registered by prefixing with ‘alphabetical’ numbering to the file names.

plugins/
  01.myPlugin.ts
  02.myOtherPlugin.ts

In this example, 02.myOtherPlugin.ts will be able to access anything that was injected by 01.myPlugin.ts.

This is useful in situations where you have a plugin that depends on another plugin.

In case you’re new to ‘alphabetical’ numbering, remember that filenames are sorted as strings, not as numeric values. For example, 10.myPlugin.ts would come before 2.myOtherPlugin.ts. This is why the example prefixes single digit numbers with 0.

Loading Strategy

Parallel Plugins

By default, Nuxt loads plugins sequentially. You can define a plugin as parallel so Nuxt won’t wait until the end of the plugin’s execution before loading the next plugin.

plugins/my-plugin.ts

export default defineNuxtPlugin({
  name: 'my-plugin',
  parallel: true,
  async setup (nuxtApp) {
    // the next plugin will be executed immediately
  },
})

Plugins With Dependencies

If a plugin needs to wait for another plugin before it runs, you can add the plugin’s name to the dependsOn array.

plugins/depending-on-my-plugin.ts

export default defineNuxtPlugin({
  name: 'depends-on-my-plugin',
  dependsOn: ['my-plugin'],
  async setup (nuxtApp) {
    // this plugin will wait for the end of `my-plugin`'s execution before it runs
  },
})

Using Composables

You can use composables as well as utils within Nuxt plugins:

app/plugins/hello.ts

export default defineNuxtPlugin((nuxtApp) => {
  const foo = useFoo()
})

However, keep in mind there are some limitations and differences:

If a composable depends on another plugin registered later, it might not work.

Plugins are called in order sequentially and before everything else. You might use a composable that depends on another plugin which has not been called yet.

If a composable depends on the Vue.js lifecycle, it won’t work.

Normally, Vue.js composables are bound to the current component instance while plugins are only bound to nuxtApp instance.

Providing Helpers

If you would like to provide a helper on the NuxtApp instance, return it from the plugin under a provide key.

plugins/hello.ts

export default defineNuxtPlugin(() => {
  return {
    provide: {
      hello: (msg: string) => `Hello ${msg}!`,
    },
  }
})

You can then use the helper in your components:

app/components/Hello.vue

<script setup lang="ts">
// alternatively, you can also use it here
const { $hello } = useNuxtApp()
</script>

<template>
  <div>
    {{ $hello('world') }}
  </div>
</template>

Note that we highly recommend using composables instead of providing helpers to avoid polluting the global namespace and keep your main bundle entry small.

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.

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

First, install the Vue plugin dependency, then create a plugin file:

app/plugins/vue-gtag.client.ts

import VueGtag, { trackRouter } from 'vue-gtag-next'

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(VueGtag, {
    property: {
      id: 'GA_MEASUREMENT_ID',
    },
  })
  trackRouter(useRouter())
})

Vue Directives

Similarly, you can register a custom Vue directive in a plugin.

plugins/my-directive.ts

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.directive('focus', {
    mounted (el) {
      el.focus()
    },
    getSSRProps (binding, vnode) {
      // you can provide SSR-specific props here
      return {}
    },
  })
})

If you register a Vue directive, you must register it on both client and server side unless you are only using it when rendering one side. If the directive only makes sense from a client side, you can always move it to ~/plugins/my-directive.client.ts and provide a ‘stub’ directive for the server in ~/plugins/my-directive.server.ts.