feat(kit,schema): add .with for better module options types (#26850)

packages/kit/src/module/define.ts

@@ -3,7 +3,7 @@ import { performance } from 'node:perf_hooks'
 import { defu } from 'defu'
 import { applyDefaults } from 'untyped'
 import { dirname } from 'pathe'
-import type { ModuleDefinition, ModuleOptions, ModuleSetupReturn, Nuxt, NuxtModule, NuxtOptions, ResolvedNuxtTemplate } from '@nuxt/schema'
+import type { ModuleDefinition, ModuleOptions, ModuleSetupInstallResult, ModuleSetupReturn, Nuxt, NuxtModule, NuxtOptions, ResolvedModuleOptions, ResolvedNuxtTemplate } from '@nuxt/schema'
 import { logger } from '../logger'
 import { nuxtCtx, tryUseNuxt, useNuxt } from '../context'
 import { checkNuxtCompatibility, isNuxt2 } from '../compatibility'
@@ -13,28 +13,53 @@ import { compileTemplate, templateUtils } from '../internal/template'
  * 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.
  */
-export function defineNuxtModule<OptionsT extends ModuleOptions> (definition: ModuleDefinition<OptionsT> | NuxtModule<OptionsT>): NuxtModule<OptionsT> {
+export function defineNuxtModule<TOptions extends ModuleOptions> (definition: ModuleDefinition<TOptions> | NuxtModule<TOptions>): NuxtModule<TOptions>
-  if (typeof definition === 'function') { return defineNuxtModule({ setup: definition }) }
 
-  // Normalize definition and meta
+export function defineNuxtModule<TOptions extends ModuleOptions> (): {
-  const module: ModuleDefinition<OptionsT> & Required<Pick<ModuleDefinition<OptionsT>, 'meta'>> = defu(definition, { meta: {} })
+  with: <TOptionsDefaults extends Partial<TOptions>> (
-  if (module.meta.configKey === undefined) {
+    definition: ModuleDefinition<TOptions, TOptionsDefaults> | NuxtModule<TOptions, TOptionsDefaults>
-    module.meta.configKey = module.meta.name
+  ) => NuxtModule<TOptions, TOptionsDefaults>
+}
+
+export function defineNuxtModule<TOptions extends ModuleOptions> (definition?: ModuleDefinition<TOptions> | NuxtModule<TOptions>) {
+  if (definition) {
+    return _defineNuxtModule(definition)
   }
 
+  return {
+    with: <TOptionsDefaults extends Partial<TOptions>>(
+      definition: ModuleDefinition<TOptions, TOptionsDefaults> | NuxtModule<TOptions, TOptionsDefaults>,
+    ) => _defineNuxtModule(definition),
+  }
+}
+
+function _defineNuxtModule<TOptions extends ModuleOptions, TOptionsDefaults extends Partial<TOptions>> (definition: ModuleDefinition<TOptions, TOptionsDefaults> | NuxtModule<TOptions, TOptionsDefaults>): NuxtModule<TOptions, TOptionsDefaults> {
+  if (typeof definition === 'function') { return _defineNuxtModule<TOptions, TOptionsDefaults>({ setup: definition }) }
+
+  // Normalize definition and meta
+  const module: ModuleDefinition<TOptions, TOptionsDefaults> & Required<Pick<ModuleDefinition<TOptions, TOptionsDefaults>, 'meta'>> = defu(definition, { meta: {} })
+
+  module.meta.configKey ||= module.meta.name
+
   // Resolves module options from inline options, [configKey] in nuxt.config, defaults and schema
-  async function getOptions (inlineOptions?: OptionsT, nuxt: Nuxt = useNuxt()) {
+  async function getOptions (inlineOptions?: Partial<TOptions>, nuxt: Nuxt = useNuxt()): Promise<ResolvedModuleOptions<TOptions, TOptionsDefaults>> {
-    const configKey = module.meta.configKey || module.meta.name!
+    const nuxtConfigOptionsKey = module.meta.configKey || module.meta.name
-    const _defaults = module.defaults instanceof Function ? module.defaults(nuxt) : module.defaults
+
-    let _options = defu(inlineOptions, nuxt.options[configKey as keyof NuxtOptions], _defaults) as OptionsT
+    const nuxtConfigOptions: Partial<TOptions> = nuxtConfigOptionsKey && nuxtConfigOptionsKey in nuxt.options ? nuxt.options[<keyof NuxtOptions> nuxtConfigOptionsKey] : {}
+
+    const optionsDefaults: TOptionsDefaults = module.defaults instanceof Function ? module.defaults(nuxt) : module.defaults ?? <TOptionsDefaults> {}
+
+    let options: ResolvedModuleOptions<TOptions, TOptionsDefaults> = defu(inlineOptions, nuxtConfigOptions, optionsDefaults)
+
     if (module.schema) {
-      _options = await applyDefaults(module.schema, _options) as OptionsT
+      options = await applyDefaults(module.schema, options) as any
     }
-    return Promise.resolve(_options)
+
+    return Promise.resolve(options)
   }
 
   // Module format is always a simple function
-  async function normalizedModule (this: any, inlineOptions: OptionsT, nuxt: Nuxt) {
+  async function normalizedModule (this: any, inlineOptions: Partial<TOptions>, nuxt: Nuxt): Promise<ModuleSetupReturn> {
     if (!nuxt) {
       nuxt = tryUseNuxt() || this.nuxt /* invoked by nuxt 2 */
     }
@@ -87,7 +112,7 @@ export function defineNuxtModule<OptionsT extends ModuleOptions> (definition: Mo
     if (res === false) { return false }
 
     // Return module install result
-    return defu(res, <ModuleSetupReturn> {
+    return defu(res, <ModuleSetupInstallResult> {
       timings: {
         setup: setupTime,
       },
@@ -98,7 +123,7 @@ export function defineNuxtModule<OptionsT extends ModuleOptions> (definition: Mo
   normalizedModule.getMeta = () => Promise.resolve(module.meta)
   normalizedModule.getOptions = getOptions
 
-  return normalizedModule as NuxtModule<OptionsT>
+  return <NuxtModule<TOptions, TOptionsDefaults>> normalizedModule
 }
 
 // -- Nuxt 2 compatibility shims --

packages/kit/src/module/install.ts

@@ -31,7 +31,7 @@ export async function installModule<
     isNuxt2()
       // @ts-expect-error Nuxt 2 `moduleContainer` is not typed
       ? await nuxtModule.call(nuxt.moduleContainer, inlineOptions, nuxt)
-      : await nuxtModule(inlineOptions, nuxt)
+      : await nuxtModule(inlineOptions || {}, nuxt)
   ) ?? {}
   if (res === false /* setup aborted */) {
     return

packages/schema/src/types/module.ts

@@ -1,3 +1,4 @@
+import type { Defu } from 'defu'
 import type { NuxtHooks } from './hooks'
 import type { Nuxt } from './nuxt'
 import type { NuxtCompatibility } from './compatibility'
@@ -26,8 +27,7 @@ export interface ModuleMeta {
 /** The options received.  */
 export type ModuleOptions = Record<string, any>
 
-/** Optional result for nuxt modules */
+export type ModuleSetupInstallResult = {
-export interface ModuleSetupReturn {
   /**
    * Timing information for the initial setup
    */
@@ -39,19 +39,37 @@ export interface ModuleSetupReturn {
 }
 
 type Awaitable<T> = T | Promise<T>
-type _ModuleSetupReturn = Awaitable<void | false | ModuleSetupReturn>
 
-/** Input module passed to defineNuxtModule. */
+type Prettify<T> = {
-export interface ModuleDefinition<T extends ModuleOptions = ModuleOptions> {
+  [K in keyof T]: T[K];
+} & {}
+
+export type ModuleSetupReturn = Awaitable<false | void | ModuleSetupInstallResult>
+
+export type ResolvedModuleOptions<TOptions extends ModuleOptions, TOptionsDefaults extends Partial<TOptions>> = Prettify<
+    Defu<
+        Partial<TOptions>,
+        [Partial<TOptions>, TOptionsDefaults]
+    >
+>
+
+/** Module definition passed to 'defineNuxtModule(...)' or 'defineNuxtModule().with(...)'. */
+export interface ModuleDefinition<
+  TOptions extends ModuleOptions,
+  TOptionsDefaults extends Partial<TOptions> = Partial<TOptions>,
+> {
   meta?: ModuleMeta
-  defaults?: T | ((nuxt: Nuxt) => T)
+  defaults?: TOptionsDefaults | ((nuxt: Nuxt) => TOptionsDefaults)
-  schema?: T
+  schema?: TOptions
   hooks?: Partial<NuxtHooks>
-  setup?: (this: void, resolvedOptions: T, nuxt: Nuxt) => _ModuleSetupReturn
+  setup?: (this: void, resolvedOptions: ResolvedModuleOptions<TOptions, TOptionsDefaults>, nuxt: Nuxt) => ModuleSetupReturn
 }
 
-export interface NuxtModule<T extends ModuleOptions = ModuleOptions> {
+export interface NuxtModule<
-  (this: void, inlineOptions: T, nuxt: Nuxt): _ModuleSetupReturn
+  TOptions extends ModuleOptions = ModuleOptions,
-  getOptions?: (inlineOptions?: T, nuxt?: Nuxt) => Promise<T>
+  TOptionsDefaults extends Partial<TOptions> = Partial<TOptions>,
+> {
+  (this: void, resolvedOptions: ResolvedModuleOptions<TOptions, TOptionsDefaults>, nuxt: Nuxt): ModuleSetupReturn
+  getOptions?: (inlineOptions?: Partial<TOptions>, nuxt?: Nuxt) => Promise<ResolvedModuleOptions<TOptions, TOptionsDefaults>>
   getMeta?: () => Promise<ModuleMeta>
 }

test/fixtures/basic-types/types.ts

@@ -5,6 +5,7 @@ import type { NavigationFailure, RouteLocationNormalized, RouteLocationRaw, Rout
 
 import type { AppConfig, RuntimeValue, UpperSnakeCase } from 'nuxt/schema'
 import { defineNuxtConfig } from 'nuxt/config'
+import { defineNuxtModule } from 'nuxt/kit'
 import { callWithNuxt, isVue3 } from '#app'
 import type { NuxtError } from '#app'
 import type { NavigateToOptions } from '#app/composables/router'
@@ -242,6 +243,23 @@ describe('modules', () => {
     // @ts-expect-error we want to ensure we throw type error on invalid key
     defineNuxtConfig({ undeclaredKey: { other: false } })
   })
+
+  it('correctly typed resolved options in defineNuxtModule setup using `.with()`', () => {
+    defineNuxtModule<{
+      foo?: string
+      baz: number
+    }>().with({
+      defaults: {
+        foo: 'bar',
+      },
+      setup: (resolvedOptions) => {
+        expectTypeOf(resolvedOptions).toEqualTypeOf<{
+          foo: string
+          baz?: number | undefined
+        }>()
+      },
+    })
+  })
 })
 
 describe('nuxtApp', () => {