Nuxt/docs/3.api/4.kit/14.builder.md

title	description
Builder	Nuxt Kit provides a set of utilities to help you work with the builder. These functions allow you to extend the webpack and vite configurations.

Builder

source code

Nuxt have builders based on webpack and vite. You can extend the config passed to each one using extendWebpackConfig and extendViteConfig functions. You can also add additional plugins via addVitePlugin, addWebpackPlugin and addBuildPlugin.

extendWebpackConfig

Extends the webpack configuration. Callback function can be called multiple times, when applying to both client and server builds.

Type

function extendWebpackConfig (callback: ((config: WebpackConfig) => void), options?: ExtendWebpackConfigOptions): void

export interface ExtendWebpackConfigOptions {
  dev?: boolean
  build?: boolean
  server?: boolean
  client?: boolean
  prepend?: boolean
}

::alert{type=info} See webpack website for more information about webpack configuration. ::

Parameters

callback

Type: (config: WebpackConfig) => void

Required: true

A callback function that will be called with the webpack configuration object.

options

Type: ExtendWebpackConfigOptions

Default: {}

Options to pass to the callback function. This object can have the following properties:

• dev (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building in development mode.

• build (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building in production mode.

• server (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building the server bundle.

• client (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building the client bundle.

• prepend (optional)

  Type: boolean

  If set to true, the callback function will be prepended to the array with unshift() instead of push().

Examples

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

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

extendViteConfig

Extends the Vite configuration. Callback function can be called multiple times, when applying to both client and server builds.

Type

function extendViteConfig (callback: ((config: ViteConfig) => void), options?: ExtendViteConfigOptions): void

export interface ExtendViteConfigOptions {
  dev?: boolean
  build?: boolean
  server?: boolean
  client?: boolean
  prepend?: boolean
}

::alert{type=info} See Vite website for more information about Vite configuration. ::

Parameters

callback

Type: (config: ViteConfig) => void

Required: true

A callback function that will be called with the Vite configuration object.

options

Type: ExtendViteConfigOptions

Default: {}

Options to pass to the callback function. This object can have the following properties:

• dev (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building in development mode.

• build (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building in production mode.

• server (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building the server bundle.

• client (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building the client bundle.

• prepend (optional)

  Type: boolean

  If set to true, the callback function will be prepended to the array with unshift() instead of push().

Examples

// https://github.com/Hrdtr/nuxt-appwrite
import { defineNuxtModule, extendViteConfig } from '@nuxt/kit'

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

addWebpackPlugin

Append webpack plugin to the config.

Type

function addWebpackPlugin (pluginOrGetter: PluginOrGetter, options?: ExtendWebpackConfigOptions): void

type PluginOrGetter = WebpackPluginInstance | WebpackPluginInstance[] | (() => WebpackPluginInstance | WebpackPluginInstance[])

interface ExtendWebpackConfigOptions {
  dev?: boolean
  build?: boolean
  server?: boolean
  client?: boolean
  prepend?: boolean
}

::alert{type=info} See webpack website for more information about webpack plugins. You can also use this collection to find a plugin that suits your needs. ::

Parameters

pluginOrGetter

Type: PluginOrGetter

Required: true

A webpack plugin instance or an array of webpack plugin instances. If a function is provided, it must return a webpack plugin instance or an array of webpack plugin instances.

options

Type: ExtendWebpackConfigOptions

Default: {}

Options to pass to the callback function. This object can have the following properties:

• dev (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building in development mode.

• build (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building in production mode.

• server (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building the server bundle.

• client (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building the client bundle.

• prepend (optional)

  Type: boolean

  If set to true, the callback function will be prepended to the array with unshift() instead of push().

Examples

// https://github.com/nuxt-modules/eslint
import EslintWebpackPlugin from 'eslint-webpack-plugin'
import { defineNuxtModule, addWebpackPlugin } 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 })
  }
})

addVitePlugin

Append Vite plugin to the config.

Type

function addVitePlugin (pluginOrGetter: PluginOrGetter, options?: ExtendViteConfigOptions): void

type PluginOrGetter = VitePlugin | VitePlugin[] | (() => VitePlugin | VitePlugin[])

interface ExtendViteConfigOptions {
  dev?: boolean
  build?: boolean
  server?: boolean
  client?: boolean
  prepend?: boolean
}

::alert{type=info} See Vite website for more information about Vite plugins. You can also use this repository to find a plugin that suits your needs. ::

Parameters

pluginOrGetter

Type: PluginOrGetter

Required: true

A Vite plugin instance or an array of Vite plugin instances. If a function is provided, it must return a Vite plugin instance or an array of Vite plugin instances.

options

Type: ExtendViteConfigOptions

Default: {}

Options to pass to the callback function. This object can have the following properties:

• dev (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building in development mode.

• build (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building in production mode.

• server (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building the server bundle.

• client (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building the client bundle.

• prepend (optional)

  Type: boolean

  If set to true, the callback function will be prepended to the array with unshift() instead of push().

Examples

// https://github.com/yisibell/nuxt-svg-icons
import { defineNuxtModule, addVitePlugin } 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))
  },
})

addBuildPlugin

Builder-agnostic version of addWebpackPlugin and addVitePlugin. It will add the plugin to both webpack and vite configurations if they are present.

Type

function addBuildPlugin (pluginFactory: AddBuildPluginFactory, options?: ExtendConfigOptions): void

interface AddBuildPluginFactory {
  vite?: () => VitePlugin | VitePlugin[]
  webpack?: () => WebpackPluginInstance | WebpackPluginInstance[]
}

interface ExtendConfigOptions {
  dev?: boolean
  build?: boolean
  server?: boolean
  client?: boolean
  prepend?: boolean
}

Parameters

pluginFactory

Type: AddBuildPluginFactory

Required: true

A factory function that returns an object with vite and/or webpack properties. These properties must be functions that return a Vite plugin instance or an array of Vite plugin instances and/or a webpack plugin instance or an array of webpack plugin instances.

options

Type: ExtendConfigOptions

Default: {}

Options to pass to the callback function. This object can have the following properties:

• dev (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building in development mode.

• build (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building in production mode.

• server (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building the server bundle.

• client (optional)

  Type: boolean

  Default: true

  If set to true, the callback function will be called when building the client bundle.

• prepend (optional)

  Type: boolean

  If set to true, the callback function will be prepended to the array with unshift() instead of push().