modules

24 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

defineNuxtModule function signature

defineNuxtModule is a function that defines a Nuxt module with automatic merging of defaults with user-provided options, installation of hooks, and optional setup function. It has two overloads: the first takes a ModuleDefinition or NuxtModule and returns a NuxtModule; the second takes no parameters and returns an object with a `.with()` method for type safety.

defineNuxtModule meta property

The meta property in a module definition is optional and of type ModuleMeta. It defines the module name, version, config key and compatibility. Example: { name: 'my-module', configKey: 'myModule', version: '1.2.0', compatibility: { nuxt: '>=3.0.0' } }

defineNuxtModule defaults property

The defaults property in a module definition is optional and can be either a default options object of type T or a function that takes the Nuxt instance and returns type T. When a function is provided, it will be called with the Nuxt instance as the first argument.

defineNuxtModule schema property

The schema property in a module definition is optional and of type T. If provided, the module options will be applied to the schema.

defineNuxtModule hooks property

The hooks property in a module definition is optional and of type Partial<NuxtHooks>. If provided, the module will install the specified hooks.

defineNuxtModule moduleDependencies property

The moduleDependencies property in a module definition is optional and specifies dependencies on other modules with version constraints and configuration. It can be either an object of type Record<string, ModuleDependency> or a function that receives the Nuxt instance and returns Record<string, ModuleDependency>. Each dependency can specify version constraints, overrides, and defaults.

defineNuxtModule onInstall property

The onInstall property in a module definition is optional and of type (nuxt: Nuxt) => Awaitable<void>. It is a lifecycle hook called only once when the module is first installed. Requires meta.name and meta.version to be defined. Runs before the setup function.

defineNuxtModule onUpgrade property

The onUpgrade property in a module definition is optional and of type (nuxt: Nuxt, options: T, previousVersion: string) => Awaitable<void>. It is a lifecycle hook called when the module is upgraded to a newer version. Requires meta.name and meta.version to be defined. Runs before the setup function and only once per version bump.

defineNuxtModule setup property

The setup property in a module definition is optional and of type (this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void | false | ModuleSetupInstallResult>. It is the setup function for the module that runs on every build. If provided, the module will call this function with resolved options and the Nuxt instance.

installModule parameters

installModule takes three parameters: moduleToInstall (required, string or NuxtModule object), inlineOptions (optional, object with module options to pass to setup function), and nuxt (optional, Nuxt instance - retrieved from context via useNuxt() if not provided).

defineNuxtModule basic usage example

import { defineNuxtModule } from '@nuxt/kit' export default defineNuxtModule({ meta: { name: 'my-module', configKey: 'myModule', }, defaults: { enabled: true, }, setup (options) { if (options.enabled) { console.log('My Nuxt module is enabled!') } }, }) This example shows how to define a basic Nuxt module with metadata, defaults, and a setup function.

defineNuxtModule configKey user configuration

When a module defines a configKey in its meta, users can provide options for the module under that key in nuxt.config. Users can also completely disable a module by setting the config key to false, which prevents the module's setup function from running while still generating types for module options.

defineNuxtModule configKey user config example

export default defineNuxtConfig({ myModule: { enabled: false, }, }) Or to disable entirely: export default defineNuxtConfig({ myModule: false, }) This shows how users configure a module that has configKey: 'myModule' in its meta.

defineNuxtModule compatibility requirements

Modules can specify Nuxt version compatibility using meta.compatibility.nuxt in semver format. If a user tries to use a module with an incompatible Nuxt version, they receive a warning in the console. Example: compatibility: { nuxt: '>=3.0.0' } or nuxt: '^3.0.0'.

defineNuxtModule .with() method for type safety

The .with() method enables type safety for resolved/merged module options. When called on defineNuxtModule<ModuleOptions>(), it allows TypeScript to properly infer the relationship between defaults and resolved options, ensuring properties with defaults are not typed as undefined in the setup function.

defineNuxtModule .with() type safety example

import { defineNuxtModule } from '@nuxt/kit' 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.baseURL is typed as string (not undefined) // resolvedOptions.timeout is typed as number (not undefined) // resolvedOptions.retries is typed as number (not undefined) console.log(resolvedOptions.baseURL) console.log(resolvedOptions.timeout) console.log(resolvedOptions.retries) }, }) This example shows how .with() enables TypeScript to understand that default values make properties non-optional in resolved options.

defineNuxtModule lifecycle hooks with example

import { defineNuxtModule } from '@nuxt/kit' import { isLess } from 'verkit' export default defineNuxtModule({ meta: { name: 'my-awesome-module', version: '1.2.0', configKey: 'myAwesomeModule', }, defaults: { apiKey: '', enabled: true, }, onInstall (nuxt) { console.log('Setting up my-awesome-module for the first time!') }, onUpgrade (nuxt, options, previousVersion) { console.log(`Upgrading my-awesome-module from ${previousVersion} to 1.2.0`) if (isLess(previousVersion, '1.1.0')) { console.log('⚠️ Breaking changes in 1.1.0') } }, setup (options, nuxt) { if (options.enabled) { // Configure the module } }, }) This example shows onInstall and onUpgrade lifecycle hooks in action.

defineNuxtModule moduleDependencies option structure

The moduleDependencies option accepts an object where each key is a module name and the value is a ModuleDependency object. Each dependency can specify: version (semver format), overrides (configuration that overrides user settings), defaults (configuration that sets defaults but respects user settings), and optional (boolean - if true, dependency won't be installed but options can be set if it is installed).

defineNuxtModule moduleDependencies example with versions and overrides

import { defineNuxtModule } from '@nuxt/kit' export default defineNuxtModule({ meta: { name: 'my-module', }, moduleDependencies: { '@nuxtjs/tailwindcss': { version: '>=6.0.0', overrides: { exposeConfig: true, }, defaults: { config: { darkMode: 'class', }, }, }, '@nuxtjs/fontaine': { optional: true, defaults: { fonts: [ { family: 'Roboto', fallbacks: ['Impact'], }, ], }, }, }, setup (options, nuxt) { }, }) This example shows how to specify module dependencies with version constraints, overrides, defaults, and optional dependencies.

defineNuxtModule moduleDependencies as function

The moduleDependencies option can also be a function that receives the Nuxt instance and returns Record<string, ModuleDependency>. This allows conditional dependencies based on the Nuxt configuration.

defineNuxtModule moduleDependencies dynamic example

import { defineNuxtModule } from '@nuxt/kit' export default defineNuxtModule({ meta: { name: 'my-module', }, moduleDependencies (nuxt) { const dependencies: Record<string, any> = { '@nuxtjs/tailwindcss': { version: '>=6.0.0', }, } if (nuxt.options.experimental?.someFeature) { dependencies['@nuxtjs/fontaine'] = { optional: true, } } return dependencies }, setup (options, nuxt) { }, }) This example shows how to use a function to conditionally determine module dependencies based on Nuxt configuration.

installModule function deprecated

installModule is deprecated. Use the moduleDependencies option in defineNuxtModule instead. The installModule function may be removed or become non-blocking in a future version.

installModule function signature

async function installModule (moduleToInstall: string | NuxtModule, inlineOptions?: any, nuxt?: Nuxt)

installModule usage example

import { defineNuxtModule, installModule } from '@nuxt/kit' export default defineNuxtModule({ async setup (options, nuxt) { await installModule('@nuxtjs/fontaine', { fonts: [ { family: 'Roboto', fallbacks: ['Impact'], fallbackName: 'fallback-a', }, ], }) }, }) This example shows how to programmatically install a module with options (deprecated approach).

Give your agent this brain