@nuxt/docs-nightly 4.0.2-29224173.3db3a78f → 4.0.2-29226089.c2c18e7e

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

@@ -44,6 +44,12 @@ import type { ModuleDefinition, ModuleOptions, NuxtModule } from '@nuxt/schema'
 export function defineNuxtModule<TOptions extends ModuleOptions> (
   definition?: ModuleDefinition<TOptions, Partial<TOptions>, false> | NuxtModule<TOptions, Partial<TOptions>, false>,
 ): NuxtModule<TOptions, TOptions, false>
+
+export function defineNuxtModule<TOptions extends ModuleOptions> (): {
+  with: <TOptionsDefaults extends Partial<TOptions>> (
+    definition: ModuleDefinition<TOptions, TOptionsDefaults, true> | NuxtModule<TOptions, TOptionsDefaults, true>
+  ) => NuxtModule<TOptions, TOptionsDefaults, true>
+}
 ```
 
 ### Parameters
@@ -122,6 +128,49 @@ If the user tries to use your module with an incompatible Nuxt version, they wil
  - [nuxt] Nuxt version ^3.1.0 is required but currently using 3.0.0
 ```
 
+#### Type Safety for Resolved Options with `.with()`
+
+When you need type safety for your resolved/merged module options, you can use the `.with()` method. This enables TypeScript to properly infer the relationship between your module's defaults and the final resolved options that your setup function receives.
+
+```ts
+import { defineNuxtModule } from '@nuxt/kit'
+
+// Define your module options interface
+interface ModuleOptions {
+  apiKey: string
+  baseURL: string
+  timeout?: number
+  retries?: number
+}
+
+export default defineNuxtModule<ModuleOptions>().with({
+  meta: {
+    name: '@nuxtjs/my-api',
+    configKey: 'myApi'
+  },
+  defaults: {
+    baseURL: 'https://api.example.com',
+    timeout: 5000,
+    retries: 3
+  },
+  setup(resolvedOptions, nuxt) {
+    // resolvedOptions is properly typed as:
+    // {
+    //   apiKey: string          // Required, no default provided
+    //   baseURL: string         // Required, has default value
+    //   timeout: number         // Optional, has default value
+    //   retries: number         // Optional, has default value  
+    // }
+    
+    console.log(resolvedOptions.baseURL) // ✅ TypeScript knows this is always defined
+    console.log(resolvedOptions.timeout) // ✅ TypeScript knows this is always defined
+    console.log(resolvedOptions.retries) // ✅ TypeScript knows this is always defined
+  }
+})
+```
+
+Without using `.with()`, the `resolvedOptions` parameter would be typed as the raw `ModuleOptions` interface, where `timeout` and `retries` could be `undefined` even when defaults are provided. The `.with()` method enables TypeScript to understand that default values make those properties non-optional in the resolved options.
+
 ## `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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.0.2-29224173.3db3a78f",
+  "version": "4.0.2-29226089.c2c18e7e",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",