feat: 위키 저장소 초기 커밋
- CLAUDE.md 운영 규칙 - wiki/ 정리된 지식 페이지 (Nuxt + Claude Code) - raw/ 원본 자료 - reference/ Nuxt 4.x 공식 문서 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
327
reference/4.api/5.kit/14.builder.md
Normal file
327
reference/4.api/5.kit/14.builder.md
Normal file
@@ -0,0 +1,327 @@
|
||||
---
|
||||
title: Builder
|
||||
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
|
||||
to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/build.ts
|
||||
size: xs
|
||||
---
|
||||
|
||||
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`.
|
||||
|
||||
## `extendViteConfig`
|
||||
|
||||
Extends the Vite configuration. Callback function can be called multiple times, when applying to both client and server builds.
|
||||
|
||||
::warning
|
||||
This hook is now deprecated, and we recommend using a Vite plugin instead with a `config` hook, or — for environment-specific configuration — the `applyToEnvironment` hook.
|
||||
::
|
||||
|
||||
### Usage
|
||||
|
||||
```ts twoslash
|
||||
import { defineNuxtModule, extendViteConfig } from '@nuxt/kit'
|
||||
|
||||
export default defineNuxtModule({
|
||||
setup () {
|
||||
extendViteConfig((config) => {
|
||||
config.optimizeDeps ||= {}
|
||||
config.optimizeDeps.include ||= []
|
||||
config.optimizeDeps.include.push('cross-fetch')
|
||||
})
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
For environment-specific configuration in Nuxt 5+, use `addVitePlugin()` instead:
|
||||
|
||||
```ts twoslash
|
||||
import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'
|
||||
|
||||
export default defineNuxtModule({
|
||||
setup () {
|
||||
// For global configuration (affects all environments)
|
||||
addVitePlugin(() => ({
|
||||
name: 'my-global-plugin',
|
||||
config (config) {
|
||||
// This runs before environment setup
|
||||
config.optimizeDeps ||= {}
|
||||
config.optimizeDeps.include ||= []
|
||||
config.optimizeDeps.include.push('cross-fetch')
|
||||
},
|
||||
}))
|
||||
|
||||
// For environment-specific configuration
|
||||
addVitePlugin(() => ({
|
||||
name: 'my-client-plugin',
|
||||
applyToEnvironment (environment) {
|
||||
return environment.name === 'client'
|
||||
},
|
||||
configEnvironment (name, config) {
|
||||
// This only affects the client environment
|
||||
config.optimizeDeps ||= {}
|
||||
config.optimizeDeps.include ||= []
|
||||
config.optimizeDeps.include.push('client-only-package')
|
||||
},
|
||||
}))
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
::warning
|
||||
**Important:** The `config` hook runs before `applyToEnvironment` and modifies the global configuration. Use `configEnvironment` for environment-specific configuration changes.
|
||||
::
|
||||
|
||||
### Type
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
::read-more{to="https://vite.dev/config/" target="_blank" icon="i-simple-icons-vite"}
|
||||
Check out the 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:
|
||||
|
||||
| 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. **Deprecated in Nuxt 5+.** Use `addVitePlugin()` with `applyToEnvironment()` instead. |
|
||||
| `client` | `boolean` | `false` | If set to `true`, the callback function will be called when building the client bundle. **Deprecated in Nuxt 5+.** Use `addVitePlugin()` with `applyToEnvironment()` instead. |
|
||||
| `prepend` | `boolean` | `false` | If 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
|
||||
|
||||
```ts twoslash
|
||||
import { defineNuxtModule, extendWebpackConfig } from '@nuxt/kit'
|
||||
|
||||
export default defineNuxtModule({
|
||||
setup () {
|
||||
extendWebpackConfig((config) => {
|
||||
config.module!.rules!.push({
|
||||
test: /\.txt$/,
|
||||
use: 'raw-loader',
|
||||
})
|
||||
})
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
### Type
|
||||
|
||||
```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://webpack.js.org/configuration/" target="_blank" icon="i-simple-icons-webpack"}
|
||||
Check out 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:
|
||||
|
||||
| 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()`. |
|
||||
|
||||
## `addVitePlugin`
|
||||
|
||||
Append Vite plugin to the config.
|
||||
|
||||
::warning
|
||||
In Nuxt 5+, plugins registered with `server: false` or `client: false` options will not have their `config` or `configResolved` hooks called. Instead, use the `applyToEnvironment()` method instead for environment-specific plugins.
|
||||
::
|
||||
|
||||
### Usage
|
||||
|
||||
```ts twoslash
|
||||
// @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))
|
||||
|
||||
// or, to add a vite plugin to only one environment
|
||||
addVitePlugin(() => ({
|
||||
name: 'my-client-plugin',
|
||||
applyToEnvironment (environment) {
|
||||
return environment.name === 'client'
|
||||
},
|
||||
// ... rest of your client-only plugin
|
||||
}))
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
### Type
|
||||
|
||||
```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 [Vite website](https://vite.dev/guide/api-plugin) 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`**: 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. The function can also be async or return a Promise, which is useful for lazy-loading plugins:
|
||||
|
||||
```ts twoslash
|
||||
// @errors: 2307
|
||||
import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'
|
||||
|
||||
export default defineNuxtModule({
|
||||
setup () {
|
||||
// Lazy load the plugin - only imported when the build actually runs
|
||||
addVitePlugin(() => import('my-vite-plugin').then(r => r.default()))
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
**`options`**: Options to pass to the callback function. This object can have the following properties:
|
||||
|
||||
| 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. **Deprecated in Nuxt 5+.** Use `applyToEnvironment()` instead. |
|
||||
| `client` | `boolean` | `false` | If set to `true`, the callback function will be called when building the client bundle. **Deprecated in Nuxt 5+.** Use `applyToEnvironment()` instead. |
|
||||
| `prepend` | `boolean` | `false` | If 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
|
||||
|
||||
```ts
|
||||
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
|
||||
|
||||
```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 [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`**: 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. The function can also be async or return a Promise, enabling lazy-loading of plugins.
|
||||
|
||||
**`options`**: Options to pass to the callback function. This object can have the following properties:
|
||||
|
||||
| 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 `addVitePlugin` and `addWebpackPlugin`. It will add the plugin to both Vite and webpack configurations if they are present.
|
||||
|
||||
### Type
|
||||
|
||||
```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[]
|
||||
}
|
||||
// ---cut---
|
||||
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:
|
||||
|
||||
| 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()`. |
|
||||
Reference in New Issue
Block a user