@nuxt/docs 4.1.3 → 4.2.1

package/3.api/5.kit/1.modules.md

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-Modules are the building blocks of Nuxt. Kit provides a set of utilities to help you create and use modules. You can use these utilities to create your own modules or to reuse existing modules. For example, you can use the `defineNuxtModule` function to define a module and the `installModule` function to install a module programmatically.
+Modules are the building blocks of Nuxt. Kit provides a set of utilities to help you create and use modules. You can use these utilities to create your own modules or to reuse existing modules. For example, you can use the `defineNuxtModule` function to define a module and specify dependencies using the `moduleDependencies` option.
 
 ## `defineNuxtModule`
 
@@ -47,7 +47,7 @@ export function defineNuxtModule<TOptions extends ModuleOptions> (
 
 export function defineNuxtModule<TOptions extends ModuleOptions> (): {
   with: <TOptionsDefaults extends Partial<TOptions>> (
-    definition: ModuleDefinition<TOptions, TOptionsDefaults, true> | NuxtModule<TOptions, TOptionsDefaults, true>
+    definition: ModuleDefinition<TOptions, TOptionsDefaults, true> | NuxtModule<TOptions, TOptionsDefaults, true>,
   ) => NuxtModule<TOptions, TOptionsDefaults, true>
 }
 ```
@@ -62,6 +62,7 @@ export function defineNuxtModule<TOptions extends ModuleOptions> (): {
 | `defaults`         | `T \| ((nuxt: Nuxt) => T)`{lang="ts"}                                | `false`  | Default options for the module. If a function is provided, it will be called with the Nuxt instance as the first argument. |
 | `schema`           | `T`                                                                  | `false`  | Schema for the module options. If provided, options will be applied to the schema.                              |
 | `hooks`            | `Partial<NuxtHooks>`{lang="ts"}                                      | `false`  | Hooks to be installed for the module. If provided, the module will install the hooks.                           |
+| `moduleDependencies` | `Record<string, ModuleDependency> \| ((nuxt: Nuxt) => Record<string, ModuleDependency>)`{lang="ts"} | `false`  | Dependencies on other modules with version constraints and configuration. Can be an object or a function that receives the Nuxt instance. See [example](/docs/4.x/api/kit/modules#specifying-module-dependencies). |
 | `onInstall`        | `(nuxt: Nuxt) => Awaitable<void>`{lang="ts"}                        | `false`  | Lifecycle hook called when the module is first installed. Requires `meta.name` and `meta.version` to be defined. |
 | `onUpgrade`        | `(options: T, nuxt: Nuxt, previousVersion: string) => Awaitable<void>`{lang="ts"} | `false`  | Lifecycle hook called when the module is upgraded to a newer version. Requires `meta.name` and `meta.version` to be defined. |
 | `setup`            | `(this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void \| false \| ModuleSetupInstallResult>`{lang="ts"} | `false`  | Setup function for the module. If provided, the module will call the setup function.    |
@@ -239,8 +240,93 @@ export default defineNuxtModule({
 })
 ```
 
+#### Specifying Module Dependencies
+
+You can use the `moduleDependencies` option to declare dependencies on other modules. This provides a robust way to ensure proper setup order, version compatibility, and configuration management.
+
+The `moduleDependencies` option can be either an object or a function that receives the Nuxt instance:
+
+##### Example
+
+```ts
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-module',
+  },
+  moduleDependencies: {
+    '@nuxtjs/tailwindcss': {
+      // Specify a version constraint (semver format)
+      version: '>=6.0.0',
+      // Configuration that overrides user settings
+      overrides: {
+        exposeConfig: true,
+      },
+      // Configuration that sets defaults but respects user settings
+      defaults: {
+        config: {
+          darkMode: 'class',
+        },
+      },
+    },
+    '@nuxtjs/fontaine': {
+      // Optional dependencies won't be installed but ensure that options
+      // can be set if they _are_ installed
+      optional: true,
+      defaults: {
+        fonts: [
+          {
+            family: 'Roboto',
+            fallbacks: ['Impact'],
+          },
+        ],
+      },
+    },
+  },
+  setup (options, nuxt) {
+
+  },
+})
+```
+
+You can also use a function to dynamically determine dependencies based on the Nuxt configuration:
+
+```ts
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-module',
+  },
+  moduleDependencies (nuxt) {
+    const dependencies: Record<string, any> = {
+      '@nuxtjs/tailwindcss': {
+        version: '>=6.0.0',
+      },
+    }
+
+    // Conditionally add dependencies based on Nuxt config
+    if (nuxt.options.experimental?.someFeature) {
+      dependencies['@nuxtjs/fontaine'] = {
+        optional: true,
+      }
+    }
+
+    return dependencies
+  },
+  setup (options, nuxt) {
+    // Your setup logic runs after all dependencies are initialized
+  },
+})
+```
+
 ## `installModule`
 
+::callout{type="warning"}
+**Deprecated:** Use the [`moduleDependencies`](/docs/4.x/api/kit/modules#specifying-module-dependencies) option in `defineNuxtModule` instead. The `installModule` function will be removed (or may become non-blocking) in a future version.
+::
+
 Install specified Nuxt module programmatically. This is helpful when your module depends on other modules. You can pass the module options as an object to `inlineOptions` and they will be passed to the module's `setup` function.
 
 ### Usage

package/3.api/5.kit/11.nitro.md

@@ -197,6 +197,10 @@ Add plugin to extend Nitro's runtime behavior.
 You can read more about Nitro plugins in the [Nitro documentation](https://nitro.build/guide/plugins).
 ::
 
+::warning
+It is necessary to explicitly import `defineNitroPlugin` from `nitropack/runtime` within your plugin file. The same requirement applies to utilities such as `useRuntimeConfig`.
+::
+
 ### Usage
 
 ```ts twoslash

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

@@ -14,6 +14,10 @@ Nuxt have builders based on [Vite](https://github.com/nuxt/nuxt/tree/main/packag
 
 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
@@ -30,6 +34,45 @@ export default defineNuxtModule({
 })
 ```
 
+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
@@ -40,8 +83,8 @@ import type { ExtendViteConfigOptions } from '@nuxt/kit'
 function extendViteConfig (callback: ((config: ViteConfig) => void), options?: ExtendViteConfigOptions): 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://vite.dev/config/" target="_blank" icon="i-simple-icons-vite"}
+Check out the Vite website for more information about its configuration.
 ::
 
 ### Parameters
@@ -54,8 +97,8 @@ Checkout Vite website for more information about its configuration.
 | --------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------ |
 | `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.                      |
+| `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`
@@ -89,8 +132,8 @@ import type { ExtendWebpackConfigOptions } from '@nuxt/kit'
 function extendWebpackConfig (callback: ((config: WebpackConfig) => void), options?: ExtendWebpackConfigOptions): void
 ```
 
-::read-more{to="https://webpack.js.org/configuration" target="_blank" icon="i-simple-icons-webpack"}
-Checkout webpack website for more information about its configuration.
+::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
@@ -111,6 +154,10 @@ Checkout webpack website for more information about its configuration.
 
 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
@@ -131,6 +178,15 @@ export default defineNuxtModule({
   },
   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
+    }))
   },
 })
 ```
@@ -146,7 +202,7 @@ function addVitePlugin (pluginOrGetter: VitePlugin | VitePlugin[] | (() => ViteP
 ```
 
 ::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 [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
@@ -159,8 +215,8 @@ See [Vite website](https://vite.dev/guide/api-plugin.html) for more information
 | --------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------ |
 | `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.                      |
+| `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`
@@ -205,7 +261,7 @@ function addWebpackPlugin (pluginOrGetter: WebpackPluginInstance | WebpackPlugin
 ```
 
 ::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 [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

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

@@ -22,11 +22,9 @@ import { buildNuxt, loadNuxt } from '@nuxt/kit'
 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_')
-      }
+    nuxt.hook('vite:extend', (config) => {
+      resolve(config)
+      throw new Error('_stop_')
     })
     buildNuxt(nuxt).catch((err) => {
       if (!err.toString().includes('_stop_')) {

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

@@ -8,7 +8,7 @@ links:
     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).
+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/test-utils).
 
 ## `loadNuxt`
 
@@ -31,7 +31,7 @@ function loadNuxt (loadOptions?: LoadNuxtOptions): Promise<Nuxt>
 
 ## `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.
+Build Nuxt programmatically. It will invoke the builder (currently [@nuxt/vite-builder](https://github.com/nuxt/nuxt/blob/main/packages/vite) or [@nuxt/webpack-builder](https://github.com/nuxt/nuxt/blob/main/packages/webpack)) to bundle the application.
 
 ### Type
 

package/3.api/5.kit/5.components.md

@@ -113,6 +113,7 @@ function addComponent (options: AddComponentOptions): void
 | ------------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |  
 | `name`             | `string`                     | `true`   | Component name.                                                                                                 |
 | `filePath`         | `string`                     | `true`   | Path to the component.                                                                                          |
+| `declarationPath`  | `string`                     | `false`  | Path to component's declaration file. It is used to generate components' [type templates](/docs/4.x/api/kit/templates#addtypetemplate); if not provided, `filePath` is used instead. |
 | `pascalName`       | `string`                     | `false`  | Pascal case component name. If not provided, it will be generated from the component name.                      |
 | `kebabName`        | `string`                     | `false`  | Kebab case component name. If not provided, it will be generated from the component name.                       |
 | `export`           | `string`                     | `false`  | Specify named or default export. If not provided, it will be set to `'default'`.                                 |

package/3.api/5.kit/9.head.md

@@ -0,0 +1,132 @@
+---
+title: Head
+description: Nuxt Kit provides utilities to help you manage head configuration in modules.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/head.ts
+    size: xs
+---
+
+## `setGlobalHead`
+
+Sets global head configuration for your Nuxt application. This utility allows modules to programmatically configure meta tags, links, scripts, and other head elements that will be applied across all pages.
+
+The provided head configuration will be merged with any existing head configuration using deep merging, with your provided values taking precedence.
+
+::tip
+This is particularly useful for modules that need to inject global meta tags, stylesheets, or scripts into the application head.
+::
+
+### Type
+
+```ts twoslash
+// @errors: 2391
+// ---cut---
+import type { SerializableHead } from '@unhead/vue/types'
+
+interface AppHeadMetaObject extends SerializableHead {
+  charset?: string
+  viewport?: string
+}
+
+function setGlobalHead (head: AppHeadMetaObject): void
+```
+
+### Parameters
+
+#### `head`
+
+**Type**: `AppHeadMetaObject`
+
+An object containing head configuration. All properties are optional and will be merged with existing configuration:
+
+- `charset`: Character encoding for the document
+- `viewport`: Viewport meta tag configuration
+- `meta`: Array of meta tag objects
+- `link`: Array of link tag objects (stylesheets, icons, etc.)
+- `style`: Array of inline style tag objects
+- `script`: Array of script tag objects
+- `noscript`: Array of noscript tag objects
+- `title`: Default page title
+- `titleTemplate`: Template for formatting page titles
+- `bodyAttrs`: Attributes to add to the `<body>` tag
+- `htmlAttrs`: Attributes to add to the `<html>` tag
+
+### Examples
+
+#### Adding Global Meta Tags
+
+```ts
+import { defineNuxtModule, setGlobalHead } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup () {
+    setGlobalHead({
+      meta: [
+        { name: 'theme-color', content: '#ffffff' },
+        { name: 'author', content: 'Your Name' },
+      ],
+    })
+  },
+})
+```
+
+#### Injecting Global Stylesheets
+
+```ts
+import { defineNuxtModule, setGlobalHead } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup () {
+    setGlobalHead({
+      link: [
+        {
+          rel: 'stylesheet',
+          href: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap',
+        },
+      ],
+    })
+  },
+})
+```
+
+#### Adding Global Scripts
+
+```ts
+import { defineNuxtModule, setGlobalHead } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup () {
+    setGlobalHead({
+      script: [
+        {
+          src: 'https://cdn.example.com/analytics.js',
+          async: true,
+          defer: true,
+        },
+      ],
+    })
+  },
+})
+```
+
+#### Setting HTML Attributes
+
+```ts
+import { defineNuxtModule, setGlobalHead } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup () {
+    setGlobalHead({
+      htmlAttrs: {
+        lang: 'en',
+        dir: 'ltr',
+      },
+      bodyAttrs: {
+        class: 'custom-body-class',
+      },
+    })
+  },
+})
+```

package/3.api/6.advanced/1.hooks.md

@@ -15,20 +15,20 @@ Hook                   | Arguments           | Environment     | Description
 `app:error`            | `err`               | Server & Client | Called when a fatal error occurs.
 `app:error:cleared`    | `{ redirect? }`     | Server & Client | Called when a fatal error occurs.
 `vue:setup`            | -                   | Server & Client | Called when the setup of Nuxt root is initialized. This callback must be synchronous.
-`vue:error`            | `err, target, info` | Server & Client | Called when a vue error propagates to the root component. [Learn More](https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured).
+`vue:error`            | `err, target, info` | Server & Client | Called when a vue error propagates to the root component. [Learn More](https://vuejs.org/api/composition-api-lifecycle#onerrorcaptured).
 `app:rendered`         | `renderContext`     | Server          | Called when SSR rendering is done.
 `app:redirected`       | -                   | Server          | Called before SSR redirection.
 `app:beforeMount`      | `vueApp`            | Client          | Called before mounting the app, called only on client side.
 `app:mounted`          | `vueApp`            | Client          | Called when Vue app is initialized and mounted in browser.
-`app:suspense:resolve` | `appComponent`      | Client          | On [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) resolved event.
+`app:suspense:resolve` | `appComponent`      | Client          | On [Suspense](https://vuejs.org/guide/built-ins/suspense#suspense) resolved event.
 `app:manifest:update`  | `{ id, timestamp }` | Client          | Called when there is a newer version of your app detected.
 `app:data:refresh`     | `keys?`             | Client          | Called when `refreshNuxtData` is called.
 `link:prefetch`        | `to`                | Client          | Called when a `<NuxtLink>` is observed to be prefetched.
-`page:start`           | `pageComponent?`    | Client          | Called on [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) inside of `NuxtPage` pending event.
-`page:finish`          | `pageComponent?`    | Client          | Called on [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) inside of `NuxtPage` resolved event.
+`page:start`           | `pageComponent?`    | Client          | Called on [Suspense](https://vuejs.org/guide/built-ins/suspense#suspense) inside of `NuxtPage` pending event.
+`page:finish`          | `pageComponent?`    | Client          | Called on [Suspense](https://vuejs.org/guide/built-ins/suspense#suspense) inside of `NuxtPage` resolved event.
 `page:loading:start`   | -                   | Client          | Called when the `setup()` of the new page is running.
 `page:loading:end`     | -                   | Client          | Called after `page:finish`
-`page:transition:finish`| `pageComponent?`    | Client          | After page transition [onAfterLeave](https://vuejs.org/guide/built-ins/transition.html#javascript-hooks) event.
+`page:transition:finish`| `pageComponent?`    | Client          | After page transition [onAfterLeave](https://vuejs.org/guide/built-ins/transition#javascript-hooks) event.
 `dev:ssr-logs`         | `logs`              | Client          | Called with an array of server-side logs that have been passed to the client (if `features.devLogs` is enabled).
 `page:view-transition:start` | `transition`        | Client          | Called after `document.startViewTransition` is called when [experimental viewTransition support is enabled](/docs/4.x/getting-started/transitions#view-transitions-api-experimental).
 
@@ -75,8 +75,8 @@ Hook                     | Arguments                  | Description
 `schema:beforeWrite`     | `schema`                   | Called before writing the given schema.
 `schema:written`         | -                          | Called after the schema is written.
 `vite:extend`            | `viteBuildContext`         | Allows extending Vite default context.
-`vite:extendConfig`      | `viteInlineConfig, env`    | Allows extending Vite default config.
-`vite:configResolved`    | `viteInlineConfig, env`    | Allows reading the resolved Vite config.
+`vite:extendConfig`      | `viteInlineConfig, env`    | Allows extending Vite default config. **Deprecated in Nuxt 5+.** In Nuxt 5, this operates on a shared configuration rather than separate client/server configs.
+`vite:configResolved`    | `viteInlineConfig, env`    | Allows reading the resolved Vite config. **Deprecated in Nuxt 5+.** In Nuxt 5, this operates on a shared configuration rather than separate client/server configs.
 `vite:serverCreated`     | `viteServer, env`          | Called when the Vite server is created.
 `vite:compiled`          | -                          | Called after Vite server is compiled.
 `webpack:config`         | `webpackConfigs`           | Called before configuring the webpack compiler.