Builder

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

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

extendViteConfig

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

Usage

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

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

Type

function extendViteConfig (callback: ((config: ViteConfig) => void), options?: ExtendViteConfigOptions): void
Checkout Vite website for more information about its configuration.

Parameters

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

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

PropertyTypeRequiredDescription
devbooleanfalseIf set to true, the callback function will be called when building in development mode.
buildbooleanfalseIf set to true, the callback function will be called when building in production mode.
serverbooleanfalseIf set to true, the callback function will be called when building the server bundle.
clientbooleanfalseIf set to true, the callback function will be called when building the client bundle.
prependbooleanfalseIf set to true, the callback function will be prepended to the array with unshift() instead of push().

extendWebpackConfig

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

Usage

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

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

Type

function extendWebpackConfig (callback: ((config: WebpackConfig) => void), options?: ExtendWebpackConfigOptions): void
Checkout webpack website for more information about its configuration.

Parameters

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

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

PropertyTypeRequiredDescription
devbooleanfalseIf set to true, the callback function will be called when building in development mode.
buildbooleanfalseIf set to true, the callback function will be called when building in production mode.
serverbooleanfalseIf set to true, the callback function will be called when building the server bundle.
clientbooleanfalseIf set to true, the callback function will be called when building the client bundle.
prependbooleanfalseIf set to true, the callback function will be prepended to the array with unshift() instead of push().

addVitePlugin

Append Vite plugin to the config.

Usage

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))
  },
})

Type

function addVitePlugin (pluginOrGetter: VitePlugin | VitePlugin[] | (() => VitePlugin | VitePlugin[]), options?: ExtendViteConfigOptions): void
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: 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: Options to pass to the callback function. This object can have the following properties:

PropertyTypeRequiredDescription
devbooleanfalseIf set to true, the callback function will be called when building in development mode.
buildbooleanfalseIf set to true, the callback function will be called when building in production mode.
serverbooleanfalseIf set to true, the callback function will be called when building the server bundle.
clientbooleanfalseIf set to true, the callback function will be called when building the client bundle.
prependbooleanfalseIf set to true, the callback function will be prepended to the array with unshift() instead of push().

addWebpackPlugin

Append webpack plugin to the config.

Usage

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 })
  },
})

Type

function addWebpackPlugin (pluginOrGetter: WebpackPluginInstance | WebpackPluginInstance[] | (() => WebpackPluginInstance | WebpackPluginInstance[]), options?: ExtendWebpackConfigOptions): void
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: 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: Options to pass to the callback function. This object can have the following properties:

PropertyTypeRequiredDescription
devbooleanfalseIf set to true, the callback function will be called when building in development mode.
buildbooleanfalseIf set to true, the callback function will be called when building in production mode.
serverbooleanfalseIf set to true, the callback function will be called when building the server bundle.
clientbooleanfalseIf set to true, the callback function will be called when building the client bundle.
prependbooleanfalseIf set to true, the callback function will be prepended to the array with unshift() instead of push().

addBuildPlugin

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

Type

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

Parameters

pluginFactory: 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: Options to pass to the callback function. This object can have the following properties:

PropertyTypeRequiredDescription
devbooleanfalseIf set to true, the callback function will be called when building in development mode.
buildbooleanfalseIf set to true, the callback function will be called when building in production mode.
serverbooleanfalseIf set to true, the callback function will be called when building the server bundle.
clientbooleanfalseIf set to true, the callback function will be called when building the client bundle.
prependbooleanfalseIf set to true, the callback function will be prepended to the array with unshift() instead of push().