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

packages/kit/src/module/define.ts

@@ -1,7 +1,7 @@
 import { performance } from 'node:perf_hooks'
 import { defu } from 'defu'
 import { applyDefaults } from 'untyped'
-import type { ModuleDefinition, ModuleOptions, ModuleSetupReturn, Nuxt, NuxtModule, NuxtOptions } from '@nuxt/schema'
+import type { ModuleDefinition, ModuleOptions, ModuleSetupInstallResult, ModuleSetupReturn, Nuxt, NuxtModule, NuxtOptions, ResolvedModuleOptions } from '@nuxt/schema'
 import { logger } from '../logger'
 import { tryUseNuxt, useNuxt } from '../context'
 import { checkNuxtCompatibility } from '../compatibility'
@@ -10,28 +10,76 @@ import { checkNuxtCompatibility } from '../compatibility'
  * 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> {
-  if (typeof definition === 'function') { return defineNuxtModule({ setup: definition }) }
+export function defineNuxtModule<TOptions extends ModuleOptions> (
+  definition: ModuleDefinition<TOptions, Partial<TOptions>, false> | NuxtModule<TOptions, Partial<TOptions>, false>
+): NuxtModule<TOptions, TOptions, false>
 
-  // Normalize definition and meta
-  const module: ModuleDefinition<OptionsT> & Required<Pick<ModuleDefinition<OptionsT>, 'meta'>> = defu(definition, { meta: {} })
-  if (module.meta.configKey === undefined) {
-    module.meta.configKey = module.meta.name
+export function defineNuxtModule<TOptions extends ModuleOptions> (): {
+  with: <TOptionsDefaults extends Partial<TOptions>> (
+    definition: ModuleDefinition<TOptions, TOptionsDefaults, true> | NuxtModule<TOptions, TOptionsDefaults, true>
+  ) => NuxtModule<TOptions, TOptionsDefaults, true>
+}
+
+export function defineNuxtModule<TOptions extends ModuleOptions> (
+  definition?: ModuleDefinition<TOptions, Partial<TOptions>, false> | NuxtModule<TOptions, Partial<TOptions>, false>,
+) {
+  if (definition) {
+    return _defineNuxtModule(definition)
   }
 
+  return {
+    with: <TOptionsDefaults extends Partial<TOptions>>(
+      definition: ModuleDefinition<TOptions, TOptionsDefaults, true> | NuxtModule<TOptions, TOptionsDefaults, true>,
+    ) => _defineNuxtModule(definition),
+  }
+}
+
+function _defineNuxtModule<
+  TOptions extends ModuleOptions,
+  TOptionsDefaults extends Partial<TOptions>,
+  TWith extends boolean,
+> (
+  definition: ModuleDefinition<TOptions, TOptionsDefaults, TWith> | NuxtModule<TOptions, TOptionsDefaults, TWith>,
+): NuxtModule<TOptions, TOptionsDefaults, TWith> {
+  if (typeof definition === 'function') {
+    return _defineNuxtModule<TOptions, TOptionsDefaults, TWith>({ setup: definition })
+  }
+
+  // Normalize definition and meta
+  const module: ModuleDefinition<TOptions, TOptionsDefaults, TWith> & Required<Pick<ModuleDefinition<TOptions, TOptionsDefaults, TWith>, '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()) {
-    const configKey = 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
+  async function getOptions (
+    inlineOptions?: Partial<TOptions>,
+    nuxt: Nuxt = useNuxt(),
+  ): Promise<
+    TWith extends true
+      ? ResolvedModuleOptions<TOptions, TOptionsDefaults>
+      : TOptions
+  > {
+    const nuxtConfigOptionsKey = module.meta.configKey || module.meta.name
+
+    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 = 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)
+
+    // @ts-expect-error ignore type mismatch when calling `defineNuxtModule` without `.with()`
+    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 */
     }
@@ -81,7 +129,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,
       },
@@ -92,5 +140,5 @@ 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, TWith>> normalizedModule
 }

packages/kit/src/module/install.ts

@@ -26,7 +26,7 @@ export async function installModule<
   }
 
   // Call module
-  const res = await nuxtModule(inlineOptions, nuxt) ?? {}
+  const res = 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 interface ModuleSetupReturn {
+export type ModuleSetupInstallResult = {
   /**
    * Timing information for the initial setup
    */
@@ -39,19 +39,62 @@ export interface ModuleSetupReturn {
 }
 
 type Awaitable<T> = T | Promise<T>
-type _ModuleSetupReturn = Awaitable<void | false | ModuleSetupReturn>
 
-/** Input module passed to defineNuxtModule. */
-export interface ModuleDefinition<T extends ModuleOptions = ModuleOptions> {
+type Prettify<T> = {
+  [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>,
+  TWith extends boolean,
+> {
   meta?: ModuleMeta
-  defaults?: T | ((nuxt: Nuxt) => T)
-  schema?: T
+  defaults?: TOptionsDefaults | ((nuxt: Nuxt) => TOptionsDefaults)
+  schema?: TOptions
   hooks?: Partial<NuxtHooks>
-  setup?: (this: void, resolvedOptions: T, nuxt: Nuxt) => _ModuleSetupReturn
+  setup?: (
+    this: void,
+    resolvedOptions: TWith extends true
+      ? ResolvedModuleOptions<TOptions, TOptionsDefaults>
+      : TOptions,
+    nuxt: Nuxt
+  ) => ModuleSetupReturn
 }
 
-export interface NuxtModule<T extends ModuleOptions = ModuleOptions> {
-  (this: void, inlineOptions: T, nuxt: Nuxt): _ModuleSetupReturn
-  getOptions?: (inlineOptions?: T, nuxt?: Nuxt) => Promise<T>
+export interface NuxtModule<
+  TOptions extends ModuleOptions = ModuleOptions,
+  TOptionsDefaults extends Partial<TOptions> = Partial<TOptions>,
+  TWith extends boolean = false,
+> {
+  (
+    this: void,
+    resolvedOptions: TWith extends true
+      ? ResolvedModuleOptions<TOptions, TOptionsDefaults>
+      : TOptions,
+    nuxt: Nuxt
+  ): ModuleSetupReturn
+  getOptions?: (
+    inlineOptions?: Partial<TOptions>,
+    nuxt?: Nuxt
+  ) => Promise<
+    TWith extends true
+      ? ResolvedModuleOptions<TOptions, TOptionsDefaults>
+      : TOptions
+  >
   getMeta?: () => Promise<ModuleMeta>
 }

test/fixtures/basic-types/types.ts

@@ -254,6 +254,23 @@ describe('modules', () => {
       },
     })
   })
+
+  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', () => {