Сборщик

Исходный код
Утилиты Nuxt Kit для расширения конфигураций Vite и webpack и подключения плагинов.

Nuxt собирает приложение через Vite и/или webpack. Конфигурацию расширяют extendViteConfig и extendWebpackConfig; плагины добавляют addVitePlugin, addWebpackPlugin и универсальный addBuildPlugin.

extendViteConfig

Расширяет конфигурацию Vite. Коллбэк может вызываться несколько раз — отдельно для клиентского и серверного бандлов.

Этот хук устарел; предпочтительнее плагин Vite с хуком config или, для настроек под окружение, хук applyToEnvironment.

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

import { defineNuxtModule, extendViteConfig } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    extendViteConfig((config) => {
      config.optimizeDeps ||= {}
      config.optimizeDeps.include ||= []
      config.optimizeDeps.include.push('cross-fetch')
    })
  },
})

Для настроек под конкретное окружение в Nuxt 5+ используйте addVitePlugin():

import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    // глобальная конфигурация (все окружения)
    addVitePlugin(() => ({
      name: 'my-global-plugin',
      config (config) {
        config.optimizeDeps ||= {}
        config.optimizeDeps.include ||= []
        config.optimizeDeps.include.push('cross-fetch')
      },
    }))

    // только клиентское окружение
    addVitePlugin(() => ({
      name: 'my-client-plugin',
      applyToEnvironment (environment) {
        return environment.name === 'client'
      },
      configEnvironment (name, config) {
        config.optimizeDeps ||= {}
        config.optimizeDeps.include ||= []
        config.optimizeDeps.include.push('client-only-package')
      },
    }))
  },
})
Важно: хук config выполняется до applyToEnvironment и меняет общую конфигурацию. Для правок под окружение используйте configEnvironment.

Тип

// @errors: 2391
import type { UserConfig as ViteConfig } from 'vite'
import type { ExtendViteConfigOptions } from '@nuxt/kit'
// ---cut---
function extendViteConfig (callback: ((config: ViteConfig) => void), options?: ExtendViteConfigOptions): void
Полное описание опций Vite — в официальной документации.

Параметры

callback: функция с объектом конфигурации Vite.

options: в каких режимах вызывать коллбэк. Поля:

СвойствоТипОбязательноОписание
devbooleanfalseПри true — в режиме разработки.
buildbooleanfalseПри true — при сборке для продакшена.
serverbooleanfalseПри true — при сборке серверного бандла.
clientbooleanfalseПри true — при сборке клиентского бандла.
prependbooleanfalseПри true коллбэк вставляется через unshift(), иначе через push().

extendWebpackConfig

Расширяет конфигурацию webpack. Коллбэк может вызываться несколько раз — для клиентского и серверного бандлов.

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

import { defineNuxtModule, extendWebpackConfig } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    extendWebpackConfig((config) => {
      config.module!.rules!.push({
        test: /\.txt$/,
        use: 'raw-loader',
      })
    })
  },
})

Тип

// @errors: 2391
import type { Configuration as WebpackConfig } from 'webpack'
import type { ExtendWebpackConfigOptions } from '@nuxt/kit'
// ---cut---
function extendWebpackConfig (callback: ((config: WebpackConfig) => void), options?: ExtendWebpackConfigOptions): void
Полное описание webpack — в официальной документации.

Параметры

callback: функция с объектом конфигурации webpack.

options: в каких режимах вызывать коллбэк:

СвойствоТипОбязательноОписание
devbooleanfalseПри true — в режиме разработки.
buildbooleanfalseПри true — при сборке для продакшена.
serverbooleanfalseПри true — при сборке серверного бандла.
clientbooleanfalseПри true — при сборке клиентского бандла.
prependbooleanfalseПри true — через unshift(), иначе push().

addVitePlugin

Добавляет плагин Vite в конфигурацию.

В Nuxt 5+ у плагинов с опциями server: false или client: false не вызываются хуки config и configResolved. Для плагинов под окружение используйте applyToEnvironment().

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

// @errors: 2307
// ---cut---
import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'
import { svg4VuePlugin } from 'vite-plugin-svg4vue'

export default defineNuxtModule({
  meta: {
    name: 'nuxt-svg-icons',
    configKey: 'nuxtSvgIcons',
  },
  defaults: {
    svg4vue: {
      assetsDirName: 'assets/icons',
    },
  },
  setup (options) {
    addVitePlugin(svg4VuePlugin(options.svg4vue))

    // или плагин только для одного окружения
    addVitePlugin(() => ({
      name: 'my-client-plugin',
      applyToEnvironment (environment) {
        return environment.name === 'client'
      },
      // ... остальная часть клиентского плагина
    }))
  },
})

Тип

// @errors: 2391
import type { Plugin as VitePlugin } from 'vite'
import type { ExtendViteConfigOptions } from '@nuxt/kit'
// ---cut---
function addVitePlugin (pluginOrGetter: VitePlugin | VitePlugin[] | (() => VitePlugin | VitePlugin[]), options?: ExtendViteConfigOptions): void
Плагины Vite — в документации; подборка — awesome-vite.

Параметры

pluginOrGetter: экземпляр плагина Vite, массив или функция, возвращающая плагин(ы). Функция может быть асинхронной или возвращать Promise — удобно для ленивой подгрузки:

// @errors: 2307
import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    // ленивая загрузка — импорт только при реальной сборке
    addVitePlugin(() => import('my-vite-plugin').then(r => r.default()))
  },
})

options: когда подключать плагин (те же флаги, что у extendViteConfig):

СвойствоТипОбязательноОписание
devbooleanfalseПри true — в режиме разработки.
buildbooleanfalseПри true — при сборке для продакшена.
serverbooleanfalseПри true — при сборке серверного бандла. Устарело в Nuxt 5+ — используйте applyToEnvironment().
clientbooleanfalseПри true — при сборке клиентского бандла. Устарело в Nuxt 5+ — используйте applyToEnvironment().
prependbooleanfalseПри true — через unshift(), иначе push().

addWebpackPlugin

Добавляет плагин webpack в конфигурацию.

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

import EslintWebpackPlugin from 'eslint-webpack-plugin'
import { addWebpackPlugin, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'nuxt-eslint',
    configKey: 'eslint',
  },
  defaults: nuxt => ({
    include: [`${nuxt.options.srcDir}/**/*.{js,jsx,ts,tsx,vue}`],
    lintOnStart: true,
  }),
  setup (options, nuxt) {
    const webpackOptions = {
      ...options,
      context: nuxt.options.srcDir,
      files: options.include,
      lintDirtyModulesOnly: !options.lintOnStart,
    }
    addWebpackPlugin(new EslintWebpackPlugin(webpackOptions), { server: false })
  },
})

Тип

// @errors: 2391
import type { WebpackPluginInstance } from 'webpack'
import type { ExtendWebpackConfigOptions } from '@nuxt/kit'
// ---cut---
function addWebpackPlugin (pluginOrGetter: WebpackPluginInstance | WebpackPluginInstance[] | (() => WebpackPluginInstance | WebpackPluginInstance[]), options?: ExtendWebpackConfigOptions): void
Плагины webpack — в документации; подборка — awesome-webpack.

Параметры

pluginOrGetter: экземпляр плагина webpack, массив или функция, возвращающая плагин(ы). Функция может быть асинхронной или возвращать Promise для ленивой подгрузки.

options: когда подключать плагин:

СвойствоТипОбязательноОписание
devbooleanfalseПри true — в режиме разработки.
buildbooleanfalseПри true — при сборке для продакшена.
serverbooleanfalseПри true — при сборке серверного бандла.
clientbooleanfalseПри true — при сборке клиентского бандла.
prependbooleanfalseПри true — через unshift(), иначе push().

addBuildPlugin

Обобщённый вариант addVitePlugin и addWebpackPlugin: плагин добавляется в Vite и webpack, если соответствующий сборщик есть в проекте.

Тип

// @errors: 2391
import type { ExtendConfigOptions } from '@nuxt/kit'
import type { Plugin as VitePlugin } from 'vite'
import type { WebpackPluginInstance } from 'webpack'
import type { RspackPluginInstance } from '@rspack/core'

interface AddBuildPluginFactory {
  vite?: () => VitePlugin | VitePlugin[]
  webpack?: () => WebpackPluginInstance | WebpackPluginInstance[]
  rspack?: () => RspackPluginInstance | RspackPluginInstance[]
}
// ---cut---
function addBuildPlugin (pluginFactory: AddBuildPluginFactory, options?: ExtendConfigOptions): void

Параметры

pluginFactory: фабрика возвращает объект с полями vite и/или webpack (и при необходимости rspack) — функции, возвращающие плагин(ы) соответствующего сборщика.

options: в каких режимах подключать плагины:

СвойствоТипОбязательноОписание
devbooleanfalseПри true — в режиме разработки.
buildbooleanfalseПри true — при сборке для продакшена.
serverbooleanfalseПри true — при сборке серверного бандла.
clientbooleanfalseПри true — при сборке клиентского бандла.
prependbooleanfalseПри true — через unshift(), иначе push().