@nuxt/docs 3.17.1 → 3.17.3

package/1.getting-started/01.introduction.md

@@ -48,7 +48,7 @@ disable SSR globally with the `ssr: false` option or leverage hybrid rendering b
 
 ### Server engine
 
-The Nuxt server engine [Nitro](https://nitro.unjs.io) unlocks new full-stack capabilities.
+The Nuxt server engine [Nitro](https://nitro.build/) unlocks new full-stack capabilities.
 
 In development, it uses Rollup and Node.js workers for your server code and context isolation. It also generates your server API by reading files in `server/api/` and server middleware from `server/middleware/`.
 

package/1.getting-started/02.installation.md

@@ -54,6 +54,10 @@ pnpm create nuxt <project-name>
 bun create nuxt <project-name>
 ```
 
+```bash [deno]
+deno -A npm:create-nuxt@latest <project-name>
+```
+
 ::
 
 ::tip
@@ -96,6 +100,10 @@ bun run dev -o
 # To use the Bun runtime during development
 # bun --bun run dev -o
 ```
+
+```bash [deno]
+deno run dev -o
+```
 ::
 
 ::tip{icon="i-lucide-circle-check"}

package/1.getting-started/03.configuration.md

@@ -149,7 +149,7 @@ Nuxt uses [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config) file a
 
 Name                                         | Config File               |  How To Configure
 ---------------------------------------------|---------------------------|-------------------------
-[Nitro](https://nitro.unjs.io)               | ~~`nitro.config.ts`~~     | Use [`nitro`](/docs/api/nuxt-config#nitro) key in `nuxt.config`
+[Nitro](https://nitro.build)               | ~~`nitro.config.ts`~~     | Use [`nitro`](/docs/api/nuxt-config#nitro) key in `nuxt.config`
 [PostCSS](https://postcss.org)               | ~~`postcss.config.js`~~   | Use [`postcss`](/docs/api/nuxt-config#postcss) key in `nuxt.config`
 [Vite](https://vite.dev)                     | ~~`vite.config.ts`~~      | Use [`vite`](/docs/api/nuxt-config#vite) key in `nuxt.config`
 [webpack](https://webpack.js.org)            | ~~`webpack.config.ts`~~   | Use [`webpack`](/docs/api/nuxt-config#webpack-1) key in `nuxt.config`

package/1.getting-started/07.routing.md

@@ -131,7 +131,7 @@ definePageMeta({
 
 Nuxt offers route validation via the `validate` property in [`definePageMeta()`](/docs/api/utils/define-page-meta) in each page you wish to validate.
 
-The `validate` property accepts the `route` as an argument. You can return a boolean value to determine whether or not this is a valid route to be rendered with this page. If you return `false`, and another match can't be found, this will cause a 404 error. You can also directly return an object with `statusCode`/`statusMessage` to respond immediately with an error (other matches will not be checked).
+The `validate` property accepts the `route` as an argument. You can return a boolean value to determine whether or not this is a valid route to be rendered with this page. If you return `false`, this will cause a 404 error. You can also directly return an object with `statusCode`/`statusMessage` to customize the error returned.
 
 If you have a more complex use case, then you can use anonymous route middleware instead.
 

package/1.getting-started/15.prerendering.md

@@ -79,7 +79,7 @@ export default defineNuxtConfig({
 
 Setting `nitro.prerender` to `true` is similar to `nitro.prerender.crawlLinks` to `true`.
 
-::read-more{to="https://nitro.unjs.io/config#prerender"}
+::read-more{to="https://nitro.build/config#prerender"}
 Read more about pre-rendering in the Nitro documentation.
 ::
 
@@ -99,7 +99,7 @@ export default defineNuxtConfig({
 });
 ```
 
-::read-more{to="https://nitro.unjs.io/config/#routerules"}
+::read-more{to="https://nitro.build/config/#routerules"}
 Read more about Nitro's `routeRules` configuration.
 ::
 

package/1.getting-started/16.deployment.md

@@ -62,7 +62,7 @@ By default, the workload gets distributed to the workers with the round robin st
 
 ### Learn More
 
-:read-more{to="https://nitro.unjs.io/deploy/node" title="the Nitro documentation for node-server preset"}
+:read-more{to="https://nitro.build/deploy/node" title="the Nitro documentation for node-server preset"}
 
 :video-accordion{title="Watch Daniel Roe's short video on the topic" videoId="0x1H6K5yOfs"}
 
@@ -111,7 +111,7 @@ export default defineNuxtConfig({
 NITRO_PRESET=node-server nuxt build
 ```
 
-🔎 Check [the Nitro deployment](https://nitro.unjs.io/deploy) for all possible deployment presets and providers.
+🔎 Check [the Nitro deployment](https://nitro.build/deploy) for all possible deployment presets and providers.
 
 ## CDN Proxy
 

package/1.getting-started/18.upgrade.md

@@ -35,9 +35,7 @@ bun x nuxi upgrade
 To use the latest Nuxt build and test features before their release, read about the [nightly release channel](/docs/guide/going-further/nightly-release-channel) guide.
 
 ::warning
-The nightly release channel `latest` tag is currently tracking the Nuxt v4 branch, meaning that it is particularly likely to have breaking changes right now - be careful!
-
-You can opt in to the 3.x branch nightly releases with `"nuxt": "npm:nuxt-nightly@3x"`.
+The nightly release channel `latest` tag is currently tracking the Nuxt v4 branch, meaning that it is particularly likely to have breaking changes right now — be careful! You can opt in to the 3.x branch nightly releases with `"nuxt": "npm:nuxt-nightly@3x"`.
 ::
 
 ## Testing Nuxt 4
@@ -76,6 +74,7 @@ export default defineNuxtConfig({
   //   spaLoadingTemplateLocation: 'within',
   //   parseErrorData: false,
   //   pendingWhenIdle: true,
+  //   alwaysRunFetchOnKeyChange: true,
   //   defaults: {
   //     useAsyncData: {
   //       deep: true
@@ -752,6 +751,46 @@ export default defineNuxtConfig({
 })
 ```
 
+### Key Change Behavior in `useAsyncData` and `useFetch`
+
+🚦 **Impact Level**: Medium
+
+#### What Changed
+
+When using reactive keys in `useAsyncData` or `useFetch`, Nuxt automatically refetches data when the key changes. When `immediate: false` is set, `useAsyncData` will only fetch data when the key changes if the data has already been fetched once.
+
+Previously, `useFetch` had slightly different behavior. It would always fetch data when the key changed.
+
+Now, `useFetch` and `useAsyncData` behave consistently - by only fetch data when the key changes if the data has already been fetched once.
+
+#### Reasons for Change
+
+This ensures consistent behavior between `useAsyncData` and `useFetch`, and prevents unexpected fetches. If you have set `immediate: false`, then you must call `refresh` or `execute` or data will never be fetched in `useFetch` or `useAsyncData`.
+
+#### Migration Steps
+
+This change should generally improve the expected behavior, but if you were expecting changing the key or options of a non-immediate `useFetch`, you now will need to trigger it manually the first time.
+
+```diff
+  const id = ref('123')
+  const { data, execute } = await useFetch('/api/test', {
+    query: { id },
+    immediate: false
+  )
++ watch(id, execute, { once: true })
+```
+
+To opt out of this behavior:
+
+```ts
+// Or globally in your Nuxt config
+export default defineNuxtConfig({
+  experimental: {
+    alwaysRunFetchOnKeyChange: true
+  }
+})
+```
+
 ### Shallow Data Reactivity in `useAsyncData` and `useFetch`
 
 🚦 **Impact Level**: Minimal

package/2.guide/1.concepts/1.auto-imports.md

@@ -54,7 +54,7 @@ const double = computed(() => count.value * 2)
 
 When you are using the built-in Composition API composables provided by Vue and Nuxt, be aware that many of them rely on being called in the right _context_.
 
-During a component lifecycle, Vue tracks the temporary instance of the current component (and similarly, Nuxt tracks a temporary instance of `nuxtApp`) via a global variable, and then unsets it in same tick. This is essential when server rendering, both to avoid cross-request state pollution (leaking a shared reference between two users) and to avoid leakage between different components.
+During a component lifecycle, Vue tracks the temporary instance of the current component (and similarly, Nuxt tracks a temporary instance of `nuxtApp`) via a global variable, and then unsets it in the same tick. This is essential when server rendering, both to avoid cross-request state pollution (leaking a shared reference between two users) and to avoid leakage between different components.
 
 That means that (with very few exceptions) you cannot use them outside a Nuxt plugin, Nuxt route middleware or Vue setup function. On top of that, you must use them synchronously - that is, you cannot use `await` before calling a composable, except within `<script setup>` blocks, within the setup function of a component declared with `defineNuxtComponent`, in `defineNuxtPlugin` or in `defineNuxtRouteMiddleware`, where we perform a transform to keep the synchronous context even after the `await`.
 

package/2.guide/1.concepts/3.rendering.md

@@ -152,7 +152,7 @@ Previously every route/page of a Nuxt application and server must use the same r
 
 Nuxt includes route rules and hybrid rendering support. Using route rules you can define rules for a group of nuxt routes, change rendering mode or assign a cache strategy based on route!
 
-Nuxt server will automatically register corresponding middleware and wrap routes with cache handlers using [Nitro caching layer](https://nitro.unjs.io/guide/cache).
+Nuxt server will automatically register corresponding middleware and wrap routes with cache handlers using [Nitro caching layer](https://nitro.build/guide/cache).
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -219,7 +219,7 @@ With ESR, the rendering process is pushed to the 'edge' of the network - the CDN
 
 When a request for a page is made, instead of going all the way to the original server, it's intercepted by the nearest edge server. This server generates the HTML for the page and sends it back to the user. This process minimizes the physical distance the data has to travel, **reducing latency and loading the page faster**.
 
-Edge-side rendering is possible thanks to [Nitro](https://nitro.unjs.io), the [server engine](/docs/guide/concepts/server-engine) that powers Nuxt. It offers cross-platform support for Node.js, Deno, Cloudflare Workers, and more.
+Edge-side rendering is possible thanks to [Nitro](https://nitro.build/), the [server engine](/docs/guide/concepts/server-engine) that powers Nuxt. It offers cross-platform support for Node.js, Deno, Cloudflare Workers, and more.
 
 The current platforms where you can leverage ESR are:
 - [Cloudflare Pages](https://pages.cloudflare.com) with zero configuration using the git integration and the `nuxt build` command

package/2.guide/1.concepts/4.server-engine.md

@@ -3,7 +3,7 @@ title: Server Engine
 description: 'Nuxt is powered by a new server engine: Nitro.'
 ---
 
-While building Nuxt, we created a new server engine: [Nitro](https://nitro.unjs.io).
+While building Nuxt, we created a new server engine: [Nitro](https://nitro.build/).
 
 It is shipped with many features:
 

package/2.guide/2.directory-structure/1.server.md

@@ -97,7 +97,7 @@ export default defineNitroPlugin((nitroApp) => {
 })
 ```
 
-:read-more{to="https://nitro.unjs.io/guide/plugins" title="Nitro Plugins" target="_blank"}
+:read-more{to="https://nitro.build/guide/plugins" title="Nitro Plugins" target="_blank"}
 
 ## Server Utilities
 
@@ -160,7 +160,7 @@ export default defineEventHandler((event) => {
 })
 ```
 
-::tip{to="https://h3.unjs.io/examples/validate-data#validate-params"}
+::tip{to="https://h3.dev/examples/validate-data#validate-params"}
 Alternatively, use `getValidatedRouterParams` with a schema validator such as Zod for runtime and type safety.
 ::
 
@@ -389,7 +389,7 @@ export default eventHandler((event) => {
 
 ### Nitro Config
 
-You can use `nitro` key in `nuxt.config` to directly set [Nitro configuration](https://nitro.unjs.io/config).
+You can use `nitro` key in `nuxt.config` to directly set [Nitro configuration](https://nitro.build/config).
 
 ::warning
 This is an advanced option. Custom config can affect production deployments, as the configuration interface might change over time when Nitro is upgraded in semver-minor versions of Nuxt.
@@ -397,7 +397,7 @@ This is an advanced option. Custom config can affect production deployments, as
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
-  // https://nitro.unjs.io/config
+  // https://nitro.build/config
   nitro: {}
 })
 ```
@@ -464,7 +464,7 @@ Never combine `next()` callback with a legacy middleware that is `async` or retu
 
 ### Server Storage
 
-Nitro provides a cross-platform [storage layer](https://nitro.unjs.io/guide/storage). In order to configure additional storage mount points, you can use `nitro.storage`, or [server plugins](#server-plugins).
+Nitro provides a cross-platform [storage layer](https://nitro.build/guide/storage). In order to configure additional storage mount points, you can use `nitro.storage`, or [server plugins](#server-plugins).
 
 **Example of adding a Redis storage:**
 
@@ -506,7 +506,7 @@ export default defineEventHandler(async (event) => {
 })
 ```
 
-::read-more{to="https://nitro.unjs.io/guide/storage" target="_blank"}
+::read-more{to="https://nitro.build/guide/storage" target="_blank"}
 Read more about Nitro Storage Layer.
 ::
 

package/2.guide/3.going-further/1.events.md

@@ -0,0 +1,82 @@
+---
+title: "Events"
+description: "Nuxt provides a powerful event system powered by hookable."
+---
+
+# Events
+
+Using events is a great way to decouple your application and allow for more flexible and modular communication between different parts of your code. Events can have multiple listeners that do not depend on each other. For example, you may wish to send an email to your user each time an order has shipped. Instead of coupling your order processing code to your email code, you can emit an event which a listener can receive and use to dispatch an email.
+
+The Nuxt event system is powered by [unjs/hookable](https://github.com/unjs/hookable), which is the same library that powers the Nuxt hooks system.
+
+## Creating Events and Listeners
+
+You can create your own custom events using the `hook` method:
+
+```ts
+const nuxtApp = useNuxtApp()
+
+nuxtApp.hook('app:user:registered', payload => {
+  console.log('A new user has registered!', payload)
+})
+```
+
+To emit an event and notify any listeners, use `callHook`:
+
+```ts
+const nuxtApp = useNuxtApp()
+
+await nuxtApp.callHook('app:user:registered', {
+  id: 1,
+  name: 'John Doe',
+})
+```
+
+You can also use the payload object to enable two-way communication between the emitter and listeners. Since the payload is passed by reference, a listener can modify it to send data back to the emitter.
+
+```ts
+const nuxtApp = useNuxtApp()
+
+nuxtApp.hook('app:user:registered', payload => {
+  payload.message = 'Welcome to our app!'
+})
+
+const payload = {
+  id: 1,
+  name: 'John Doe',
+}
+
+await nuxtApp.callHook('app:user:registered', {
+  id: 1,
+  name: 'John Doe',
+})
+
+// payload.message will be 'Welcome to our app!'
+```
+
+::tip
+You can inspect all events using the **Nuxt DevTools** Hooks panel.
+::
+
+## Augmenting Types
+
+You can augment the types of hooks provided by Nuxt.
+
+```ts
+import { HookResult } from "@nuxt/schema";
+
+declare module '#app' {
+  interface RuntimeNuxtHooks {
+    'your-nuxt-runtime-hook': () => HookResult
+  }
+  interface NuxtHooks {
+    'your-nuxt-hook': () => HookResult
+  }
+}
+
+declare module 'nitropack' {
+  interface NitroRuntimeHooks {
+    'your-nitro-hook': () => void;
+  }
+}
+```

package/2.guide/3.going-further/11.nightly-release-channel.md

@@ -16,9 +16,7 @@ Features that are only available on the nightly release channel are marked with
 ::
 
 ::warning
-The `latest` nightly release channel is currently tracking the Nuxt v4 branch, meaning that it is particularly likely to have breaking changes right now - be careful!
-
-You can opt in to the 3.x branch nightly releases with `"nuxt": "npm:nuxt-nightly@3x"`.
+The `latest` nightly release channel is currently tracking the Nuxt v4 branch, meaning that it is particularly likely to have breaking changes right now — be careful! You can opt in to the 3.x branch nightly releases with `"nuxt": "npm:nuxt-nightly@3x"`.
 ::
 
 ## Opting In

package/2.guide/3.going-further/2.hooks.md

@@ -76,23 +76,4 @@ Learn more about available Nitro lifecycle hooks.
 
 ## Additional Hooks
 
-You can add additional hooks by augmenting the types provided by Nuxt. This can be useful for modules.
-
-```ts
-import { HookResult } from "@nuxt/schema";
-
-declare module '#app' {
-  interface RuntimeNuxtHooks {
-    'your-nuxt-runtime-hook': () => HookResult
-  }
-  interface NuxtHooks {
-    'your-nuxt-hook': () => HookResult
-  }
-}
-
-declare module 'nitropack' {
-  interface NitroRuntimeHooks {
-    'your-nitro-hook': () => void;
-  }
-}
-```
+Learn more about creating custom hooks in the [Events section](/docs/guide/going-further/events).

package/2.guide/3.going-further/3.modules.md

@@ -24,7 +24,7 @@ yarn create nuxt -t module my-module
 ```
 
 ```bash [pnpm]
-pnpm create nuxt -- -t module my-module
+pnpm create nuxt -t module my-module
 ```
 
 ```bash [bun]

package/3.api/2.composables/use-request-url.md

@@ -11,9 +11,9 @@ links:
 `useRequestURL` is a helper function that returns an [URL object](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) working on both server-side and client-side.
 
 ::important
-When utilizing [Hybrid Rendering](/docs/guide/concepts/rendering#hybrid-rendering) with cache strategies, all incoming request headers are dropped when handling the cached responses via the [Nitro caching layer](https://nitro.unjs.io/guide/cache) (meaning `useRequestURL` will return `localhost` for the `host`).
+When utilizing [Hybrid Rendering](/docs/guide/concepts/rendering#hybrid-rendering) with cache strategies, all incoming request headers are dropped when handling the cached responses via the [Nitro caching layer](https://nitro.build/guide/cache) (meaning `useRequestURL` will return `localhost` for the `host`).
 
-You can define the [`cache.varies` option](https://nitro.unjs.io/guide/cache#options) to specify headers that will be considered when caching and serving the responses, such as `host` and `x-forwarded-host` for multi-tenant environments.
+You can define the [`cache.varies` option](https://nitro.build/guide/cache#options) to specify headers that will be considered when caching and serving the responses, such as `host` and `x-forwarded-host` for multi-tenant environments.
 ::
 
 ::code-group

package/3.api/3.utils/navigate-to.md

@@ -17,7 +17,7 @@ Make sure to always use `await` or `return` on result of `navigateTo` when calli
 ::
 
 ::note
-`navigateTo` cannot be used within Nitro routes. To perform a server-side redirect in Nitro routes, use [`sendRedirect`](https://h3.unjs.io/utils/response#sendredirectevent-location-code) instead.
+`navigateTo` cannot be used within Nitro routes. To perform a server-side redirect in Nitro routes, use [`sendRedirect`](https://h3.dev/utils/response#sendredirectevent-location-code) instead.
 ::
 
 ### Within a Vue Component

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

@@ -14,87 +14,57 @@ Modules are the building blocks of Nuxt. Kit provides a set of utilities to help
 
 Define a Nuxt module, automatically merging defaults with user provided options, installing any hooks that are provided, and calling an optional setup function for full control.
 
-### Type
+### Usage
 
-```ts
-function defineNuxtModule<OptionsT extends ModuleOptions> (definition: ModuleDefinition<OptionsT> | NuxtModule<OptionsT>): NuxtModule<OptionsT>
-
-type ModuleOptions = Record<string, any>
-
-interface ModuleDefinition<T extends ModuleOptions = ModuleOptions> {
-  meta?: ModuleMeta
-  defaults?: T | ((nuxt: Nuxt) => T)
-  schema?: T
-  hooks?: Partial<NuxtHooks>
-  setup?: (this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void | false | ModuleSetupReturn>
-}
-
-interface NuxtModule<T extends ModuleOptions = ModuleOptions> {
-  (this: void, inlineOptions: T, nuxt: Nuxt): Awaitable<void | false | ModuleSetupReturn>
-  getOptions?: (inlineOptions?: T, nuxt?: Nuxt) => Promise<T>
-  getMeta?: () => Promise<ModuleMeta>
-}
-
-interface ModuleSetupReturn {
-  timings?: {
-    setup?: number
-    [key: string]: number | undefined
+```ts twoslash
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-module',
+    configKey: 'myModule'
+  },
+  defaults: {
+    enabled: true
+  },
+  setup (options) {
+    if (options.enabled) {
+      console.log('My Nuxt module is enabled!')
+    }
   }
-}
-
-interface ModuleMeta {
-  name?: string
-  version?: string
-  configKey?: string
-  compatibility?: NuxtCompatibility
-  [key: string]: unknown
-}
+})
 ```
 
-### Parameters
-
-#### `definition`
-
-**Type**: `ModuleDefinition<T> | NuxtModule<T>`
-
-**Required**: `true`
-
-A module definition object or a module function.
-
-- `meta` (optional)
-
-  **Type**: `ModuleMeta`
-
-  Metadata of the module. It defines the module name, version, config key and compatibility.
-
-- `defaults` (optional)
-
-  **Type**: `T | ((nuxt: Nuxt) => T)`
-
-  Default options for the module. If a function is provided, it will be called with the Nuxt instance as the first argument.
-
-- `schema` (optional)
-
-  **Type**: `T`
-
-  Schema for the module options. If provided, options will be applied to the schema.
+### Type
 
-- `hooks` (optional)
+```ts twoslash
+// @errors: 2391
+import type { ModuleDefinition, ModuleOptions, NuxtModule } from '@nuxt/schema'
+// ---cut---
+export function defineNuxtModule<TOptions extends ModuleOptions> (
+  definition?: ModuleDefinition<TOptions, Partial<TOptions>, false> | NuxtModule<TOptions, Partial<TOptions>, false>,
+): NuxtModule<TOptions, TOptions, false>
+```
 
-  **Type**: `Partial<NuxtHooks>`
+### Parameters
 
-  Hooks to be installed for the module. If provided, the module will install the hooks.
+**definition**: A module definition object or a module function. The module definition object should contain the following properties:
 
-- `setup` (optional)
+| Property           | Type                                                                 | Required | Description                                                                                                     |
+| ------------------ | -------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `meta`             | `ModuleMeta`                                                         | `false`  | Metadata of the module. It defines the module name, version, config key and compatibility.                      |
+| `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.                           |
+| `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.    |
 
-  **Type**: `(this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void | false | ModuleSetupReturn>`
+### Examples
 
-  Setup function for the module. If provided, the module will call the setup function.
+#### Using `configKey` to Make Your Module Configurable
 
-### Examples
+When defining a Nuxt module, you can set a `configKey` to specify how users should configure the module in their `nuxt.config`.
 
 ```ts
-// https://github.com/nuxt/starter/tree/module
 import { defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
@@ -103,51 +73,94 @@ export default defineNuxtModule({
     configKey: 'myModule'
   },
   defaults: {
-    test: 123
+    // Module options
+    enabled: true
   },
-  setup (options, nuxt) {
-    nuxt.hook('modules:done', () => {
-      console.log('My module is ready with current test option: ', options.test)
-    })    
+  setup (options) {
+    if (options.enabled) {
+      console.log('My Nuxt module is enabled!')
+    }
   }
 })
 ```
 
-## `installModule`
-
-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.
-
-### Type
+Users can provide options for this module under the corresponding key in `nuxt.config`.
 
 ```ts
-async function installModule (moduleToInstall: string | NuxtModule, inlineOptions?: any, nuxt?: Nuxt)
+export default defineNuxtConfig({
+  myModule: {
+    enabled: false
+  }
+})
 ```
 
-### Parameters
+#### Defining Module Compatibility Requirements
+
+If you're developing a Nuxt module and using APIs that are only supported in specific Nuxt versions, it's highly recommended to include `compatibility.nuxt`.
 
-#### `moduleToInstall`
+```ts
+export default defineNuxtModule({
+  meta: {
+    name: '@nuxt/icon',
+    configKey: 'icon',
+    compatibility: {
+      // Required nuxt version in semver format.
+      nuxt: '>=3.0.0', // or use '^3.0.0'
+    },
+  },
+  async setup() {
+    const resolver = createResolver(import.meta.url)
+    // Implement
+  },
+})
+```
 
-**Type**: `string` | `NuxtModule`
+If the user tries to use your module with an incompatible Nuxt version, they will receive a warning in the console.
 
-**Required**: `true`
+```terminal
+ WARN  Module @nuxt/icon is disabled due to incompatibility issues:
+ - [nuxt] Nuxt version ^3.1.0 is required but currently using 3.0.0
+```
 
-The module to install. Can be either a string with the module name or a module object itself.
+## `installModule`
 
-#### `inlineOptions`
+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.
 
-**Type**: `any`
+### Usage
 
-**Default**: `{}`
+```ts twoslash
+import { defineNuxtModule, installModule } from '@nuxt/kit'
 
-An object with the module options to be passed to the module's `setup` function.
+export default defineNuxtModule({  
+  async setup () {
+    // will install @nuxtjs/fontaine with Roboto font and Impact fallback
+    await installModule('@nuxtjs/fontaine', {
+      // module configuration
+      fonts: [
+        {
+          family: 'Roboto',
+          fallbacks: ['Impact'],
+          fallbackName: 'fallback-a',
+        }
+      ]
+    })
+  }
+})
+```
 
-#### `nuxt`
+### Type
 
-**Type**: `Nuxt`
+```ts
+async function installModule (moduleToInstall: string | NuxtModule, inlineOptions?: any, nuxt?: Nuxt)
+```
 
-**Default**: `useNuxt()`
+### Parameters
 
-Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
+| Property           | Type                                         | Required | Description                                                                                                     |
+| ------------------ | -------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `moduleToInstall`  | `string \| NuxtModule`{lang="ts"}            | `true`   | The module to install. Can be either a string with the module name or a module object itself.                   |
+| `inlineOptions`    | `any`                                        | `false`  | An object with the module options to be passed to the module's `setup` function.                                |
+| `nuxt`             | `Nuxt`                                       | `false`  | Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.                     |
 
 ### Examples