defineNuxtPlugin

Исходный код
Функция defineNuxtPlugin() — вспомогательная обёртка для создания плагинов Nuxt.

defineNuxtPlugin — вспомогательная функция для плагинов Nuxt с расширенными возможностями и типобезопасностью. Приводит разные форматы плагинов к единой структуре, совместимой с системой плагинов Nuxt.

plugins/hello.ts
export default defineNuxtPlugin((nuxtApp) => {
  // работа с nuxtApp
})
Узнать больше Docs > 3 X > Directory Structure > Plugins#creating Plugins.

Тип

type Plugin<T> = (nuxt: NuxtApp) => 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>
  env?: {
    islands?: boolean
  }
}

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

Параметры

plugin: плагин задаётся двумя способами:

  1. Плагин-функция: функция, получающая экземпляр NuxtApp; может вернуть промис с объектом и полем provide, чтобы передать во NuxtApp вспомогательные функции или другие значения.
  2. Объектный плагин: объект с полями для настройки плагина: name, enforce, dependsOn, order, parallel, setup, hooks, env и др.
СвойствоТипОбязательноОписание
namestringfalseНеобязательное имя плагина — удобно для отладки и управления зависимостями.
enforce'pre' | 'default' | 'post'falseЗадаёт порядок запуска относительно других плагинов.
dependsOnstring[]falseИмена плагинов, от которых зависит этот; задаёт порядок выполнения.
ordernumberfalseТочная сортировка плагинов; только для продвинутых сценариев. Переопределяет enforce при сортировке.
parallelbooleanfalseЗапускать ли плагин параллельно с другими помеченными как параллельные.
setupPlugin<T>falseОсновная функция плагина — эквивалент «функционального» плагина.
hooksPartial<RuntimeNuxtHooks>falseХуки runtime-приложения Nuxt для прямой регистрации.
env{ islands?: boolean }falseУкажите false, чтобы плагин не выполнялся при рендере только серверных или island-компонентов.

Примеры

Базовое использование

Ниже — простой плагин, добавляющий глобальную функциональность:

plugins/hello.ts
export default defineNuxtPlugin((nuxtApp) => {
  // глобальный метод
  return {
    provide: {
      hello: (name: string) => `Привет, ${name}!`,
    },
  }
})

Плагин в объектном синтаксисе

Ниже — объектный синтаксис с дополнительной настройкой:

plugins/advanced.ts
export default defineNuxtPlugin({
  name: 'my-plugin',
  enforce: 'pre',
  async setup (nuxtApp) {
    // логика инициализации плагина
    const data = await $fetch('/api/config')

    return {
      provide: {
        config: data,
      },
    }
  },
  hooks: {
    'app:created' () {
      console.log('Приложение создано')
    },
  },
})