@nuxt/docs 0.0.0 → 3.17.1

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

@@ -0,0 +1,491 @@
+---
+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.
+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 [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`.
+
+## `extendWebpackConfig`
+
+Extends the webpack configuration. Callback function can be called multiple times, when applying to both client and server builds.
+
+### Type
+
+```ts
+function extendWebpackConfig (callback: ((config: WebpackConfig) => void), options?: ExtendWebpackConfigOptions): void
+
+export interface ExtendWebpackConfigOptions {
+  dev?: boolean
+  build?: boolean
+  server?: boolean
+  client?: boolean
+  prepend?: boolean
+}
+```
+
+::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`
+
+  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
+
+```ts
+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
+
+```ts
+function extendViteConfig (callback: ((config: ViteConfig) => void), options?: ExtendViteConfigOptions): void
+
+export interface ExtendViteConfigOptions {
+  dev?: boolean
+  build?: boolean
+  server?: boolean
+  client?: boolean
+  prepend?: boolean
+}
+```
+
+::read-more{to="https://vite.dev/config" target="_blank" icon="i-simple-icons-vite"}
+Checkout Vite 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`
+
+  **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/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
+
+```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
+}
+```
+
+::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`
+
+**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
+
+```ts
+// 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
+
+```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
+}
+```
+
+::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.
+::
+
+### 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
+
+```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))
+  },
+})
+```
+
+## `addBuildPlugin`
+
+Builder-agnostic version of `addWebpackPlugin` and `addVitePlugin`. It will add the plugin to both webpack and vite configurations if they are present.
+
+### Type
+
+```ts
+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()`.

package/3.api/5.kit/15.examples.md

@@ -0,0 +1,41 @@
+---
+title: "Examples"
+description: Examples of Nuxt Kit utilities in use.
+---
+
+## Accessing Nuxt Vite Config
+
+If you are building an integration that needs access to the runtime Vite or webpack config that Nuxt uses, it is possible to extract this using Kit utilities.
+
+Some examples of projects doing this already:
+
+- [histoire](https://github.com/histoire-dev/histoire/blob/main/packages/histoire-plugin-nuxt/src/index.ts)
+- [nuxt-vitest](https://github.com/danielroe/nuxt-vitest/blob/main/packages/nuxt-vitest/src/config.ts)
+- [@storybook-vue/nuxt](https://github.com/storybook-vue/storybook-nuxt/blob/main/packages/storybook-nuxt/src/preset.ts)
+
+Here is a brief example of how you might access the Vite config from a project; you could implement a similar approach to get the webpack configuration.
+
+```js
+import { loadNuxt, buildNuxt } from '@nuxt/kit'
+
+// https://github.com/nuxt/nuxt/issues/14534
+async function getViteConfig() {
+  const nuxt = await loadNuxt({ cwd: process.cwd(), dev: false, overrides: { ssr: false } })
+  return new Promise((resolve, reject) => {
+    nuxt.hook('vite:extendConfig', (config, { isClient }) => {
+      if (isClient) {
+        resolve(config)
+        throw new Error('_stop_')
+      }
+    })
+    buildNuxt(nuxt).catch((err) => {
+      if (!err.toString().includes('_stop_')) {
+        reject(err)
+      }
+    })
+  }).finally(() => nuxt.close())
+}
+
+const viteConfig = await getViteConfig()
+console.log(viteConfig)
+```

package/3.api/5.kit/2.programmatic.md

@@ -0,0 +1,125 @@
+---
+title: "Programmatic Usage"
+description: Nuxt Kit provides a set of utilities to help you work with Nuxt programmatically. These functions allow you to load Nuxt, build Nuxt, and load Nuxt configuration.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/loader
+    size: xs
+---
+
+Programmatic usage can be helpful when you want to use Nuxt programmatically, for example, when building a [CLI tool](https://github.com/nuxt/cli) or [test utils](https://github.com/nuxt/nuxt/tree/main/packages/test-utils).
+
+## `loadNuxt`
+
+Load Nuxt programmatically. It will load the Nuxt configuration, instantiate and return the promise with Nuxt instance.
+
+### Type
+
+```ts
+async function loadNuxt (loadOptions?: LoadNuxtOptions): Promise<Nuxt>
+
+interface LoadNuxtOptions extends LoadNuxtConfigOptions {
+  dev?: boolean
+  ready?: boolean
+}
+```
+
+### Parameters
+
+#### `loadOptions`
+
+**Type**: `LoadNuxtOptions`
+
+**Default**: `{}`
+
+Loading conditions for Nuxt. `loadNuxt` uses [`c12`](https://github.com/unjs/c12) under the hood, so it accepts the same options as `c12.loadConfig` with some additional options:
+
+- `dev` (optional)
+
+  **Type**: `boolean`
+
+  **Default**: `false`
+
+  If set to `true`, Nuxt will be loaded in development mode.
+
+- `ready` (optional)
+  
+  **Type**: `boolean`
+  
+  **Default**: `true`
+  
+  If set to `true`, Nuxt will be ready to use after the `loadNuxt` call. If set to `false`, you will need to call `nuxt.ready()` to make sure Nuxt is ready to use.
+
+## `buildNuxt`
+
+Build Nuxt programmatically. It will invoke the builder (currently [@nuxt/vite-builder](https://github.com/nuxt/nuxt/tree/main/packages/vite) or [@nuxt/webpack-builder](https://github.com/nuxt/nuxt/tree/main/packages/webpack)) to bundle the application.
+
+### Type
+
+```ts
+async function buildNuxt (nuxt: Nuxt): Promise<any>
+```
+
+### Parameters
+
+#### `nuxt`
+
+**Type**: `Nuxt`
+
+**Required**: `true`
+
+Nuxt instance to build. It can be retrieved from the context via `useNuxt()` call.
+
+## `loadNuxtConfig`
+
+Load Nuxt configuration. It will return the promise with the configuration object.
+
+### Type
+
+```ts
+async function loadNuxtConfig (options: LoadNuxtConfigOptions): Promise<NuxtOptions>
+```
+
+### Parameters
+
+#### `options`
+
+**Type**: `LoadNuxtConfigOptions`
+
+**Required**: `true`
+
+Options to pass in [`c12`](https://github.com/unjs/c12#options) `loadConfig` call.
+
+## `writeTypes`
+
+Generates `tsconfig.json` and writes it to the project buildDir.
+
+### Type
+
+```ts
+function writeTypes (nuxt?: Nuxt): void
+
+interface Nuxt {
+  options: NuxtOptions
+  hooks: Hookable<NuxtHooks>
+  hook: Nuxt['hooks']['hook']
+  callHook: Nuxt['hooks']['callHook']
+  addHooks: Nuxt['hooks']['addHooks']
+  ready: () => Promise<void>
+  close: () => Promise<void>
+  server?: any
+  vfs: Record<string, string>
+  apps: Record<string, NuxtApp>
+}
+```
+
+### Parameters
+
+#### `nuxt`
+
+**Type**: `Nuxt`
+
+**Required**: `true`
+
+Nuxt instance to build. It can be retrieved from the context via `useNuxt()` call.