v4 (alpha)
Nuxt on GitHub

defineNuxtPlugin

Source
defineNuxtPlugin() is a helper function for creating Nuxt plugins.

defineNuxtPlugin is a helper function for creating Nuxt plugins with enhanced functionality and type safety. This utility normalizes different plugin formats into a consistent structure that works seamlessly within Nuxt's plugin system.

plugins/hello.ts
export default defineNuxtPlugin((nuxtApp) => {
  // Doing something with nuxtApp
})
Read more in Docs > Guide > Directory Structure > Plugins#creating Plugins.

Type

defineNuxtPlugin<T extends Record<string, unknown>>(plugin: Plugin<T> | ObjectPlugin<T>): Plugin<T> & ObjectPlugin<T>

type Plugin<T> = (nuxt: [NuxtApp](/docs/4.x/guide/going-further/internals#the-nuxtapp-interface)) => Promise<void> | Promise<{ provide?: T }> | void | { provide?: T }

interface ObjectPlugin<T> {
  name?: string
  enforce?: 'pre' | 'default' | 'post'
  dependsOn?: string[]
  order?: number
  parallel?: boolean
  setup?: Plugin<T>
  hooks?: Partial<[RuntimeNuxtHooks](/docs/4.x/api/advanced/hooks#app-hooks-runtime)>
  env?: {
    islands?: boolean
  }
}

Parameters

plugin: A plugin can be defined in two ways:

  1. Function Plugin: A function that receives the NuxtApp instance and can return a promise with an potential object with a provide property if you want to provide a helper on NuxtApp instance.
  2. Object Plugin: An object that can include various properties to configure the plugin's behavior, such as name, enforce, dependsOn, order, parallel, setup, hooks, and env.
PropertyTypeRequiredDescription
namestringfalseOptional name for the plugin, useful for debugging and dependency management.
enforce'pre' | 'default' | 'post'falseControls when the plugin runs relative to other plugins.
dependsOnstring[]falseArray of plugin names this plugin depends on. Ensures proper execution order.
ordernumberfalseThis allows more granular control over plugin order and should only be used by advanced users. It overrides the value of enforce and is used to sort plugins.
parallelbooleanfalseWhether to execute the plugin in parallel with other parallel plugins.
setupPlugin<T>falseThe main plugin function, equivalent to a function plugin.
hooksPartial<RuntimeNuxtHooks>falseNuxt app runtime hooks to register directly.
env{ islands?: boolean }falseSet this value to false if you don't want the plugin to run when rendering server-only or island components.

Examples

Basic Usage

The example below demonstrates a simple plugin that adds global functionality:

plugins/hello.ts
export default defineNuxtPlugin((nuxtApp) => {
  // Add a global method
  return {
    provide: {
      hello: (name: string) => `Hello ${name}!`
    }
  }
})

Object Syntax Plugin

The example below shows the object syntax with advanced configuration:

plugins/advanced.ts
export default defineNuxtPlugin({
  name: 'my-plugin',
  enforce: 'pre',
  async setup (nuxtApp) {
    // Plugin setup logic
    const data = await $fetch('/api/config')
    
    return {
      provide: {
        config: data
      }
    }
  },
  hooks: {
    'app:created'() {
      console.log('App created!')
    }
  },
})