0
# Module System
1

2
The module system provides core functionality for defining, installing, and managing Nuxt modules. It includes tools for module definition with automatic option merging, installation utilities, and compatibility checking.
3

4
## Capabilities
5

6
### Module Definition
7

8
Define Nuxt modules with automatic option merging, setup hooks, and builder pattern support.
9

10
```typescript { .api }
11
/**
12
 * Define a Nuxt module with automatic option merging and setup
13
 * @param definition - Module definition with meta, defaults, and setup function
14
 * @returns NuxtModule instance or builder object with .with() method
15
 */
16
function defineNuxtModule<T>(definition: ModuleDefinition<T>): NuxtModule<T>;
17

18
interface ModuleDefinition<T> {
19
  meta?: ModuleMeta;
20
  defaults?: T | ((nuxt: Nuxt) => T);
21
  schema?: Schema;
22
  hooks?: Partial<NuxtHooks>;
23
  setup?: (options: T, nuxt: Nuxt) => void | Promise<void>;
24
}
25

26
interface ModuleMeta {
27
  name?: string;
28
  version?: string;
29
  configKey?: string;
30
  compatibility?: NuxtCompatibility;
31
}
32

33
interface NuxtModule<T = any> {
34
  (this: void, inlineOptions: T, nuxt: Nuxt): void | Promise<void>;
35
  getOptions?: (inlineOptions?: T, nuxt?: Nuxt) => Promise<T>;
36
  getMeta?: () => Promise<ModuleMeta>;
37
}
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
import { defineNuxtModule } from "@nuxt/kit";
44

45
// Basic module definition
46
export default defineNuxtModule({
47
  meta: {
48
    name: "my-module",
49
    configKey: "myModule"
50
  },
51
  defaults: {
52
    enabled: true,
53
    apiUrl: "https://api.example.com"
54
  },
55
  setup(options, nuxt) {
56
    // Module setup logic
57
    console.log(`Module enabled: ${options.enabled}`);
58
  }
59
});
60

61
// Builder pattern with .with()
62
export default defineNuxtModule({
63
  meta: { name: "my-module" },
64
  setup() {
65
    // Base setup
66
  }
67
}).with({
68
  // Extended configuration
69
  apiKey: process.env.API_KEY
70
});
71
```
72

73
### Module Installation
74

75
Install and manage Nuxt modules programmatically.
76

77
```typescript { .api }
78
/**
79
 * Install a module on a Nuxt instance (deprecated - use module dependencies instead)
80
 * @param moduleToInstall - Module to install (string path, function, or object)
81
 * @param inlineOptions - Options to pass to the module
82
 * @param nuxt - Nuxt instance (defaults to current context)
83
 * @returns Promise resolving to installed NuxtModule
84
 */
85
function installModule<T>(
86
  moduleToInstall: T,
87
  inlineOptions?: any,
88
  nuxt?: Nuxt
89
): Promise<NuxtModule>;
90

91
/**
92
 * Install a set of modules on a Nuxt instance (internal function)
93
 * @param modulesToInstall - Map of modules to install with their options
94
 * @param resolvedModulePaths - Set of already resolved module paths
95
 * @param nuxt - Nuxt instance (defaults to current context)
96
 * @returns Promise that resolves when all modules are installed
97
 * @internal
98
 */
99
function installModules(
100
  modulesToInstall: Map<ModuleToInstall, Record<string, any>>,
101
  resolvedModulePaths: Set<string>,
102
  nuxt?: Nuxt
103
): Promise<void>;
104

105
/**
106
 * Resolve module with options from module definition
107
 * @param definition - Module definition (string, array, or NuxtModule)
108
 * @param nuxt - Nuxt instance to use for resolution
109
 * @returns Resolved module information or undefined if not resolvable
110
 */
111
function resolveModuleWithOptions(
112
  definition: NuxtModule<any> | string | false | undefined | null | [(NuxtModule | string)?, Record<string, any>?],
113
  nuxt: Nuxt
114
): { resolvedPath?: string, module: string | NuxtModule<any>, options: Record<string, any> } | undefined;
115

116
/**
117
 * Load and resolve a Nuxt module instance
118
 * @param nuxtModule - Module identifier (string path or NuxtModule)
119
 * @param nuxt - Nuxt instance (defaults to current context)
120
 * @returns Promise resolving to loaded NuxtModule
121
 */
122
function loadNuxtModuleInstance(
123
  nuxtModule: string | NuxtModule,
124
  nuxt?: Nuxt
125
): Promise<NuxtModule>;
126

127
/**
128
 * Get directory path from module file path
129
 * @param p - Module file path
130
 * @returns Directory path string
131
 */
132
function getDirectory(p: string): string;
133

134
/**
135
 * Normalize module path for transpilation
136
 * @param p - Module path to normalize
137
 * @returns Normalized path string
138
 */
139
function normalizeModuleTranspilePath(p: string): string;
140
```
141

142
### Module Compatibility
143

144
Check and validate module compatibility with current Nuxt version.
145

146
```typescript { .api }
147
/**
148
 * Check if a Nuxt module is installed by name
149
 * @param moduleName - Name of the module to check
150
 * @param nuxt - Nuxt instance (defaults to current context)
151
 * @returns True if module is installed
152
 */
153
function hasNuxtModule(moduleName: string, nuxt?: Nuxt): boolean;
154

155
/**
156
 * Get version of an installed Nuxt module
157
 * @param module - Module name or NuxtModule instance
158
 * @param nuxt - Nuxt instance (defaults to current context)
159
 * @returns Promise resolving to version string or false if not found
160
 */
161
function getNuxtModuleVersion(
162
  module: string | NuxtModule,
163
  nuxt?: Nuxt
164
): Promise<string | false>;
165

166
/**
167
 * Check if module is compatible with given semver version
168
 * @param module - Module name or NuxtModule instance
169
 * @param semverVersion - Semantic version constraint
170
 * @param nuxt - Nuxt instance (defaults to current context)
171
 * @returns Promise resolving to compatibility boolean
172
 */
173
function hasNuxtModuleCompatibility(
174
  module: string | NuxtModule,
175
  semverVersion: string,
176
  nuxt?: Nuxt
177
): Promise<boolean>;
178
```
179

180
**Usage Examples:**
181

182
```typescript
183
import { 
184
  hasNuxtModule, 
185
  getNuxtModuleVersion, 
186
  hasNuxtModuleCompatibility 
187
} from "@nuxt/kit";
188

189
// Check if module is installed
190
if (hasNuxtModule("@nuxtjs/tailwindcss")) {
191
  console.log("Tailwind CSS module is installed");
192
}
193

194
// Get module version
195
const version = await getNuxtModuleVersion("@nuxtjs/tailwindcss");
196
console.log(`Tailwind CSS version: ${version}`);
197

198
// Check compatibility
199
const isCompatible = await hasNuxtModuleCompatibility(
200
  "@nuxtjs/tailwindcss",
201
  "^6.0.0"
202
);
203
```
204

205
## Types
206

207
```typescript { .api }
208
interface NuxtCompatibility {
209
  nuxt?: string;
210
  bridge?: boolean;
211
}
212

213
interface Schema {
214
  [key: string]: any;
215
}
216

217
interface NuxtHooks {
218
  [key: string]: (...args: any[]) => any;
219
}
220

221
type ModuleToInstall = string | NuxtModule<any, Partial<any>, false>;
222
```