@nuxt/docs-nightly 4.0.0-29102016.0f2ddb79 → 4.0.0-29102890.1505fb54

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/3.api/5.kit/1.modules.md

@@ -14,87 +14,52 @@ 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
+function defineNuxtModule (definition: ModuleDefinition | NuxtModule): NuxtModule
+```
 
-  **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 +68,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
 

package/3.api/5.kit/10.runtime-config.md

@@ -22,6 +22,8 @@ function useRuntimeConfig (): Record<string, unknown>
 
 It is also possible to update runtime configuration. This will be merged with the existing runtime configuration, and if Nitro has already been initialized it will trigger an HMR event to reload the Nitro runtime config.
 
+### Type
+
 ```ts
 function updateRuntimeConfig (config: Record<string, unknown>): void | Promise<void>
 ```