diff --git a/docs/3.api/4.advanced/2.kit.md b/docs/3.api/4.advanced/2.kit.md index aab126160a..708d36678b 100644 --- a/docs/3.api/4.advanced/2.kit.md +++ b/docs/3.api/4.advanced/2.kit.md @@ -12,6 +12,114 @@ description: Nuxt Kit provides composable utilities to help interacting with Nux [source code](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/module) +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. + +### `defineNuxtModule` + +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 + +```ts +function defineNuxtModule (definition: ModuleDefinition | NuxtModule): NuxtModule + +type ModuleOptions = Record + +interface ModuleDefinition { + meta?: ModuleMeta + defaults?: T | ((nuxt: Nuxt) => T) + schema?: T + hooks?: Partial + setup?: (this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable +} + +interface NuxtModule { + (this: void, inlineOptions: T, nuxt: Nuxt): Awaitable + getOptions?: (inlineOptions?: T, nuxt?: Nuxt) => Promise + getMeta?: () => Promise +} + +interface ModuleSetupReturn { + timings?: { + setup?: number + [key: string]: number | undefined + } +} + +interface ModuleMeta { + name?: string + version?: string + configKey?: string + compatibility?: NuxtCompatibility + [key: string]: unknown +} +``` + +#### Parameters + +##### `definition` + +**Type**: `ModuleDefinition | NuxtModule` + +**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. + +- `hooks` (optional) + + **Type**: `Partial` + + Hooks to be installed for the module. If provided, the module will install the hooks. + +- `setup` (optional) + + **Type**: `(this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable` + + Setup function for the module. If provided, the module will call the setup function. + +#### Examples + +```ts +// https://github.com/nuxt/starter/tree/module +import { defineNuxtModule } from '@nuxt/kit' + +export interface ModuleOptions {} + +export default defineNuxtModule({ + meta: { + name: 'my-module', + configKey: 'myModule' + }, + defaults: { + test: 123 + }, + setup (options, nuxt) { + nuxt.hook('modules:done', () => { + console.log('My module is ready with current test option: ', options.test) + }) + } +}) +``` + + ### `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.