feat(docs): defineNuxtModule

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<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
+  }
+}
+
+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.
+
+- `hooks` (optional)
+
+  **Type**: `Partial<NuxtHooks>`
+
+  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<void | false | ModuleSetupReturn>`
+
+  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<ModuleOptions>({
+  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.