defineNuxtPlugin

defineNuxtPlugin() é uma função auxiliar para criar plugins Nuxt.

defineNuxtPlugin é uma função auxiliar para criar plugins Nuxt com funcionalidade aprimorada e segurança de tipos. Esta utilidade normaliza diferentes formatos de plugins em uma estrutura consistente que funciona perfeitamente dentro do sistema de plugins do Nuxt.

plugins/hello.ts

export default defineNuxtPlugin((nuxtApp) => {
  // Fazendo algo com nuxtApp
})

Veja também 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: Um plugin pode ser definido de duas maneiras:

Function Plugin: Uma função que recebe a instância do NuxtApp e pode retornar uma promessa com um objeto potencial com uma propriedade provide se você quiser fornecer um auxiliar na instância do NuxtApp.
Object Plugin: Um objeto que pode incluir várias propriedades para configurar o comportamento do plugin, como name, enforce, dependsOn, order, parallel, setup, hooks e env.

Propriedade	Tipo	Obrigatório	Descrição
`name`	`string`	`false`	Nome opcional para o plugin, útil para depuração e gerenciamento de dependências.
`enforce`	`'pre'` \| `'default'` \| `'post'`	`false`	Controla quando o plugin é executado em relação a outros plugins.
`dependsOn`	`string[]`	`false`	Array de nomes de plugins dos quais este plugin depende. Garante a ordem correta de execução.
`order`	`number`	`false`	Isso permite um controle mais granular sobre a ordem dos plugins e deve ser usado apenas por usuários avançados. Ele substitui o valor de `enforce` e é usado para classificar plugins.
`parallel`	`boolean`	`false`	Se o plugin deve ser executado em paralelo com outros plugins paralelos.
`setup`	`Plugin<T>`	`false`	A função principal do plugin, equivalente a um plugin de função.
`hooks`	`Partial<RuntimeNuxtHooks>`	`false`	Hooks de runtime do aplicativo Nuxt para registrar diretamente.
`env`	`{ islands?: boolean }`	`false`	Defina este valor como `false` se você não quiser que o plugin seja executado ao renderizar componentes apenas do servidor ou ilhas.

Exemplos

Uso Básico

O exemplo abaixo demonstra um plugin simples que adiciona funcionalidade global:

plugins/hello.ts

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

Plugin com Sintaxe de Objeto

O exemplo abaixo mostra a sintaxe de objeto com configuração avançada:

plugins/advanced.ts

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

※Esta página é uma tradução não oficial da documentação oficial do Nuxt.js.

A página correspondente na documentação oficial está aqui:
https://nuxt.com/docs/3.x/api/utils/define-nuxt-plugin