@nuxt/docs 3.17.0 → 3.17.2

package/3.api/5.kit/14.builder.md

@@ -1,6 +1,6 @@
 ---
 title: Builder
-description: 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.
+description: 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.
 links:
   - label: Source
     icon: i-simple-icons-github
@@ -8,284 +8,170 @@ links:
     size: xs
 ---
 
-Nuxt have builders based on [webpack](https://github.com/nuxt/nuxt/tree/main/packages/webpack) and [vite](https://github.com/nuxt/nuxt/tree/main/packages/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`.
+Nuxt have builders based on [Vite](https://github.com/nuxt/nuxt/tree/main/packages/vite) and [webpack](https://github.com/nuxt/nuxt/tree/main/packages/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`.
 
-## `extendWebpackConfig`
+## `extendViteConfig`
 
-Extends the webpack configuration. Callback function can be called multiple times, when applying to both client and server builds.
+Extends the Vite configuration. Callback function can be called multiple times, when applying to both client and server builds.
 
-### Type
+### Usage
 
-```ts
-function extendWebpackConfig (callback: ((config: WebpackConfig) => void), options?: ExtendWebpackConfigOptions): void
+```ts twoslash
+import { defineNuxtModule, extendViteConfig } from '@nuxt/kit'
 
-export interface ExtendWebpackConfigOptions {
-  dev?: boolean
-  build?: boolean
-  server?: boolean
-  client?: boolean
-  prepend?: boolean
-}
+export default defineNuxtModule({
+  setup () {
+    extendViteConfig((config) => {
+      config.optimizeDeps ||= {}
+      config.optimizeDeps.include ||= []
+      config.optimizeDeps.include.push('cross-fetch')
+    })
+  },
+})
 ```
 
-::read-more{to="https://webpack.js.org/configuration" target="_blank" icon="i-simple-icons-webpack"}
-Checkout webpack website for more information about its 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`
+### Type
 
-  If set to `true`, the callback function will be called when building the server bundle.
+```ts twoslash
+// @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
+```
 
-- `client` (optional)
+::read-more{to="https://vite.dev/config" target="_blank" icon="i-simple-icons-vite"}
+Checkout Vite website for more information about its configuration.
+::
 
-  **Type**: `boolean`
+### Parameters
 
-  **Default**: `true`
+**`callback`**: A callback function that will be called with the Vite configuration object.
 
-  If set to `true`, the callback function will be called when building the client bundle.
+**`options`**: Options to pass to the callback function. This object can have the following properties:
 
-- `prepend` (optional)
+| Property  | Type      | Required | Description                                                                                                 |
+| --------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------ |
+| `dev`     | `boolean` | `false`  | If set to `true`, the callback function will be called when building in development mode.                    |
+| `build`   | `boolean` | `false`  | If set to `true`, the callback function will be called when building in production mode.                     |
+| `server`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the server bundle.                      |
+| `client`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the client bundle.                      |
+| `prepend` | `boolean` | `false`  | If set to `true`, the callback function will be prepended to the array with `unshift()` instead of `push()`. |
 
-  **Type**: `boolean`
+## `extendWebpackConfig`
 
-  If set to `true`, the callback function will be prepended to the array with `unshift()` instead of `push()`.
+Extends the webpack configuration. Callback function can be called multiple times, when applying to both client and server builds.
 
-### Examples
+### Usage
 
-```ts
+```ts twoslash
 import { defineNuxtModule, extendWebpackConfig } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup() {
+  setup () {
     extendWebpackConfig((config) => {
-      config.module?.rules.push({
+      config.module!.rules!.push({
         test: /\.txt$/,
-        use: 'raw-loader'
+        use: 'raw-loader',
       })
     })
-  }
+  },
 })
 ```
 
-## `extendViteConfig`
-
-Extends the Vite configuration. Callback function can be called multiple times, when applying to both client and server builds.
-
 ### Type
 
-```ts
-function extendViteConfig (callback: ((config: ViteConfig) => void), options?: ExtendViteConfigOptions): void
-
-export interface ExtendViteConfigOptions {
-  dev?: boolean
-  build?: boolean
-  server?: boolean
-  client?: boolean
-  prepend?: boolean
-}
+```ts twoslash
+// @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
 ```
 
-::read-more{to="https://vite.dev/config" target="_blank" icon="i-simple-icons-vite"}
-Checkout Vite website for more information about its configuration.
+::read-more{to="https://webpack.js.org/configuration" target="_blank" icon="i-simple-icons-webpack"}
+Checkout webpack website for more information about its 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`
+**`callback`**: A callback function that will be called with the webpack configuration object.
 
-  **Default**: `true`
+**`options`**: Options to pass to the callback function. This object can have the following properties:
 
-  If set to `true`, the callback function will be called when building the client bundle.
+| Property  | Type      | Required | Description                                                                                                  |
+| --------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------ |
+| `dev`     | `boolean` | `false`  | If set to `true`, the callback function will be called when building in development mode.                    |
+| `build`   | `boolean` | `false`  | If set to `true`, the callback function will be called when building in production mode.                     |
+| `server`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the server bundle.                      |
+| `client`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the client bundle.                      |
+| `prepend` | `boolean` | `false`  | If set to `true`, the callback function will be prepended to the array with `unshift()` instead of `push()`. |
 
-- `prepend` (optional)
-
-  **Type**: `boolean`
+## `addVitePlugin`
 
-  If set to `true`, the callback function will be prepended to the array with `unshift()` instead of `push()`.
+Append Vite plugin to the config.
 
-### Examples
+### Usage
 
-```ts
-// https://github.com/Hrdtr/nuxt-appwrite
-import { defineNuxtModule, extendViteConfig } from '@nuxt/kit'
+```ts twoslash
+// @errors: 2307
+// ---cut---
+import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'
+import { svg4VuePlugin } from 'vite-plugin-svg4vue'
 
 export default defineNuxtModule({
-  setup() {
-    extendViteConfig((config) => {
-      config.optimizeDeps = config.optimizeDeps || {}
-      config.optimizeDeps.include = config.optimizeDeps.include || []
-      config.optimizeDeps.include.push('cross-fetch')
-    })
-  }
+  meta: {
+    name: 'nuxt-svg-icons',
+    configKey: 'nuxtSvgIcons',
+  },
+  defaults: {
+    svg4vue: {
+      assetsDirName: 'assets/icons',
+    },
+  },
+  setup (options) {
+    addVitePlugin(svg4VuePlugin(options.svg4vue))
+  },
 })
 ```
 
-## `addWebpackPlugin`
-
-Append webpack plugin to the config.
-
 ### Type
 
-```ts
-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
-}
+```ts twoslash
+// @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
 ```
 
 ::tip
-See [webpack website](https://webpack.js.org/concepts/plugins) for more information about webpack plugins. You can also use [this collection](https://webpack.js.org/awesome-webpack/#webpack-plugins) to find a plugin that suits your needs.
+See [Vite website](https://vite.dev/guide/api-plugin.html) for more information about Vite plugins. You can also use [this repository](https://github.com/vitejs/awesome-vite#plugins) 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.
+**`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.
 
-- `build` (optional)
+**`options`**: Options to pass to the callback function. This object can have the following properties:
 
-  **Type**: `boolean`
+| Property  | Type      | Required | Description                                                                                                 |
+| --------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------ |
+| `dev`     | `boolean` | `false`  | If set to `true`, the callback function will be called when building in development mode.                    |
+| `build`   | `boolean` | `false`  | If set to `true`, the callback function will be called when building in production mode.                     |
+| `server`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the server bundle.                      |
+| `client`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the client bundle.                      |
+| `prepend` | `boolean` | `false`  | If set to `true`, the callback function will be prepended to the array with `unshift()` instead of `push()`. |
 
-  **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`
+## `addWebpackPlugin`
 
-  If set to `true`, the callback function will be prepended to the array with `unshift()` instead of `push()`.
+Append webpack plugin to the config.
 
-### Examples
+### Usage
 
 ```ts
-// https://github.com/nuxt-modules/eslint
 import EslintWebpackPlugin from 'eslint-webpack-plugin'
-import { defineNuxtModule, addWebpackPlugin } from '@nuxt/kit'
+import { addWebpackPlugin, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
   meta: {
@@ -296,196 +182,77 @@ export default defineNuxtModule({
     include: [`${nuxt.options.srcDir}/**/*.{js,jsx,ts,tsx,vue}`],
     lintOnStart: true,
   }),
-  setup(options, nuxt) {
+  setup (options, nuxt) {
     const webpackOptions = {
       ...options,
       context: nuxt.options.srcDir,
       files: options.include,
-      lintDirtyModulesOnly: !options.lintOnStart
+      lintDirtyModulesOnly: !options.lintOnStart,
     }
     addWebpackPlugin(new EslintWebpackPlugin(webpackOptions), { server: false })
-  }
+  },
 })
 ```
 
-## `addVitePlugin`
-
-Append Vite plugin to the config.
-
 ### Type
 
-```ts
-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
-}
+```ts twoslash
+// @errors: 2391
+import type { WebpackPluginInstance } from 'webpack'
+import type { ExtendWebpackConfigOptions } from '@nuxt/kit'
+// ---cut---
+function addWebpackPlugin (pluginOrGetter: WebpackPluginInstance | WebpackPluginInstance[] | (() => WebpackPluginInstance | WebpackPluginInstance[]), options?: ExtendWebpackConfigOptions): void
 ```
 
 ::tip
-See [Vite website](https://vite.dev/guide/api-plugin.html) for more information about Vite plugins. You can also use [this repository](https://github.com/vitejs/awesome-vite#plugins) to find a plugin that suits your needs.
+See [webpack website](https://webpack.js.org/concepts/plugins) for more information about webpack plugins. You can also use [this collection](https://webpack.js.org/awesome-webpack/#webpack-plugins) 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`
+**`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.
 
-  If set to `true`, the callback function will be called when building the server bundle.
+**`options`**: Options to pass to the callback function. This object can have the following properties:
 
-- `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
-
-```ts
-// 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))
-  },
-})
-```
+| Property  | Type      | Required | Description                                                                                                 |
+| --------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------ |
+| `dev`     | `boolean` | `false`  | If set to `true`, the callback function will be called when building in development mode.                    |
+| `build`   | `boolean` | `false`  | If set to `true`, the callback function will be called when building in production mode.                     |
+| `server`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the server bundle.                      |
+| `client`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the client bundle.                      |
+| `prepend` | `boolean` | `false`  | If set to `true`, the callback function will be prepended to the array with `unshift()` instead of `push()`. |
 
 ## `addBuildPlugin`
 
-Builder-agnostic version of `addWebpackPlugin` and `addVitePlugin`. It will add the plugin to both webpack and vite configurations if they are present.
+Builder-agnostic version of `addVitePlugin` and `addWebpackPlugin`. It will add the plugin to both Vite and webpack configurations if they are present.
 
 ### Type
 
-```ts
-function addBuildPlugin (pluginFactory: AddBuildPluginFactory, options?: ExtendConfigOptions): void
-
+```ts twoslash
+// @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[]
 }
-
-interface ExtendConfigOptions {
-  dev?: boolean
-  build?: boolean
-  server?: boolean
-  client?: boolean
-  prepend?: boolean
-}
+// ---cut---
+function addBuildPlugin (pluginFactory: AddBuildPluginFactory, options?: ExtendConfigOptions): void
 ```
 
 ### 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)
+**`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.
 
-  **Type**: `boolean`
+**`options`**: Options to pass to the callback function. This object can have the following properties:
 
-  If set to `true`, the callback function will be prepended to the array with `unshift()` instead of `push()`.
+| Property  | Type      | Required | Description                                                                                                 |
+| --------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------ |
+| `dev`     | `boolean` | `false`  | If set to `true`, the callback function will be called when building in development mode.                    |
+| `build`   | `boolean` | `false`  | If set to `true`, the callback function will be called when building in production mode.                     |
+| `server`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the server bundle.                      |
+| `client`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the client bundle.                      |
+| `prepend` | `boolean` | `false`  | If set to `true`, the callback function will be prepended to the array with `unshift()` instead of `push()`. |