defineNuxtPlugin

defineNuxtPlugin() es una función auxiliar para crear plugins de Nuxt.

defineNuxtPlugin es una función auxiliar para crear plugins de Nuxt con funcionalidad mejorada y seguridad de tipos. Esta utilidad normaliza diferentes formatos de plugins en una estructura coherente que funciona sin problemas dentro del sistema de plugins de Nuxt.

plugins/hello.ts

export default defineNuxtPlugin((nuxtApp) => {
  // Haciendo algo con nuxtApp
})

Ver también guide > directory-structure > plugins#creating-plugins

Tipo

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

type Plugin<T> = (nuxt: [NuxtApp](/docs/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/api/advanced/hooks#app-hooks-runtime)>
  env?: {
    islands?: boolean
  }
}

Parámetros

plugin: Un plugin puede definirse de dos maneras:

Function Plugin: Una función que recibe la instancia de NuxtApp y puede devolver una promesa con un objeto potencial con una propiedad provide si deseas proporcionar un helper en la instancia de NuxtApp.
Object Plugin: Un objeto que puede incluir varias propiedades para configurar el comportamiento del plugin, como name, enforce, dependsOn, order, parallel, setup, hooks y env.

Propiedad	Tipo	Requerido	Descripción
`name`	`string`	`false`	Nombre opcional para el plugin, útil para depuración y gestión de dependencias.
`enforce`	`'pre'` \| `'default'` \| `'post'`	`false`	Controla cuándo se ejecuta el plugin en relación con otros plugins.
`dependsOn`	`string[]`	`false`	Array de nombres de plugins de los que depende este plugin. Asegura el orden de ejecución adecuado.
`order`	`number`	`false`	Esto permite un control más granular sobre el orden de los plugins y solo debe ser usado por usuarios avanzados. Sobrescribe el valor de `enforce` y se usa para ordenar los plugins.
`parallel`	`boolean`	`false`	Indica si se debe ejecutar el plugin en paralelo con otros plugins paralelos.
`setup`	`Plugin<T>{lang="ts"}`	`false`	La función principal del plugin, equivalente a un plugin de función.
`hooks`	`Partial<RuntimeNuxtHooks>{lang="ts"}`	`false`	Hooks de tiempo de ejecución de la aplicación Nuxt para registrar directamente.
`env`	`{ islands?: boolean }{lang="ts"}`	`false`	Establece este valor en `false` si no deseas que el plugin se ejecute al renderizar componentes solo del servidor o de isla.

Ejemplos

Uso Básico

El siguiente ejemplo demuestra un plugin simple que agrega funcionalidad global:

plugins/hello.ts

export default defineNuxtPlugin((nuxtApp) => {
  // Agregar un método global
  return {
    provide: {
      hello: (name: string) => `Hello ${name}!`
    }
  }
})

Plugin con Sintaxis de Objeto

El siguiente ejemplo muestra la sintaxis de objeto con configuración avanzada:

plugins/advanced.ts

export default defineNuxtPlugin({
  name: 'my-plugin',
  enforce: 'pre',
  async setup (nuxtApp) {
    // Lógica de configuración del plugin
    const data = await $fetch('/api/config')
    
    return {
      provide: {
        config: data
      }
    }
  },
  hooks: {
    'app:created'() {
      console.log('¡App creada!')
    }
  },
})

※Esta página es una traducción no oficial de la documentación oficial de Nuxt.js.

La página correspondiente en la documentación oficial está aquí:
https://nuxt.com/docs/3.x/api/utils/define-nuxt-plugin