0
# Compatibility Utilities
1

2
Version checking, compatibility validation, and migration support tools for ensuring module compatibility across different Nuxt versions.
3

4
## Capabilities
5

6
### Version Information
7

8
Get current Nuxt version and check version compatibility.
9

10
```typescript { .api }
11
/**
12
 * Get current Nuxt version
13
 * @param nuxt - Nuxt instance (defaults to current context)
14
 * @returns Nuxt version string
15
 */
16
function getNuxtVersion(nuxt?: Nuxt): string;
17

18
/**
19
 * Check if current Nuxt instance is of specified major version
20
 * @param majorVersion - Major version to check (2, 3, or 4)
21
 * @param nuxt - Nuxt instance (defaults to current context)
22
 * @returns True if major version matches
23
 */
24
function isNuxtMajorVersion(majorVersion: 2 | 3 | 4, nuxt?: Nuxt): boolean;
25

26
/**
27
 * Normalize semantic version by removing edge prefixes
28
 * @param version - Version string to normalize
29
 * @returns Normalized semantic version
30
 */
31
function normalizeSemanticVersion(version: string): string;
32
```
33

34
**Usage Examples:**
35

36
```typescript
37
import { 
38
  getNuxtVersion, 
39
  isNuxtMajorVersion, 
40
  normalizeSemanticVersion 
41
} from "@nuxt/kit";
42

43
// Get current version
44
const version = getNuxtVersion();
45
console.log(`Running Nuxt ${version}`);
46

47
// Check major version
48
if (isNuxtMajorVersion(3)) {
49
  console.log("Running Nuxt 3");
50
} else if (isNuxtMajorVersion(2)) {
51
  console.log("Running Nuxt 2");
52
}
53

54
// Normalize version strings
55
const normalized = normalizeSemanticVersion("3.0.0-edge.1");
56
// Returns: "3.0.0"
57
```
58

59
### Compatibility Checking
60

61
Check and validate compatibility constraints with detailed reporting.
62

63
```typescript { .api }
64
/**
65
 * Check if constraints are satisfied
66
 * @param constraints - Compatibility constraints
67
 * @param nuxt - Nuxt instance (defaults to current context)
68
 * @returns Promise resolving to compatibility boolean
69
 */
70
function hasNuxtCompatibility(
71
  constraints: NuxtCompatibility,
72
  nuxt?: Nuxt
73
): Promise<boolean>;
74

75
/**
76
 * Check version constraints and return incompatibility issues
77
 * @param constraints - Compatibility constraints
78
 * @param nuxt - Nuxt instance (defaults to current context)
79
 * @returns Promise resolving to compatibility issues
80
 */
81
function checkNuxtCompatibility(
82
  constraints: NuxtCompatibility,
83
  nuxt?: Nuxt
84
): Promise<NuxtCompatibilityIssues>;
85

86
/**
87
 * Assert compatibility constraints, throw error if failed
88
 * @param constraints - Compatibility constraints
89
 * @param nuxt - Nuxt instance (defaults to current context)
90
 * @returns Promise resolving to true if compatible
91
 * @throws Error if compatibility check fails
92
 */
93
function assertNuxtCompatibility(
94
  constraints: NuxtCompatibility,
95
  nuxt?: Nuxt
96
): Promise<true>;
97

98
interface NuxtCompatibility {
99
  /** Nuxt version constraint (semver range) */
100
  nuxt?: string;
101
  /** Bridge compatibility flag */
102
  bridge?: boolean;
103
  /** Node.js version constraint */
104
  node?: string;
105
}
106

107
interface NuxtCompatibilityIssues extends Array<NuxtCompatibilityIssue> {
108
  /** Return formatted error message */
109
  toString(): string;
110
}
111

112
interface NuxtCompatibilityIssue {
113
  /** Issue name/type */
114
  name: string;
115
  /** Issue description */
116
  message: string;
117
}
118
```
119

120
**Usage Examples:**
121

122
```typescript
123
import { 
124
  hasNuxtCompatibility, 
125
  checkNuxtCompatibility, 
126
  assertNuxtCompatibility 
127
} from "@nuxt/kit";
128

129
// Simple compatibility check
130
const isCompatible = await hasNuxtCompatibility({
131
  nuxt: "^3.0.0"
132
});
133

134
if (isCompatible) {
135
  console.log("Module is compatible");
136
}
137

138
// Detailed compatibility check
139
const issues = await checkNuxtCompatibility({
140
  nuxt: "^3.0.0",
141
  bridge: false,
142
  node: ">=16.0.0"
143
});
144

145
if (issues.length > 0) {
146
  console.log("Compatibility issues found:");
147
  issues.forEach(issue => {
148
    console.log(`- ${issue.name}: ${issue.message}`);
149
  });
150
  
151
  // Or use the formatted output
152
  console.log(issues.toString());
153
}
154

155
// Assert compatibility (throws on failure)
156
try {
157
  await assertNuxtCompatibility({
158
    nuxt: "^3.0.0"
159
  });
160
  console.log("Compatibility check passed");
161
} catch (error) {
162
  console.error("Compatibility check failed:", error.message);
163
}
164
```
165

166
### Module-Level Compatibility
167

168
Use compatibility checking within module definitions.
169

170
```typescript { .api }
171
export default defineNuxtModule({
172
  meta: {
173
    name: "my-module",
174
    compatibility: {
175
      nuxt: "^3.0.0",
176
      bridge: false
177
    }
178
  },
179
  async setup(options, nuxt) {
180
    // Manual compatibility check
181
    await assertNuxtCompatibility({
182
      nuxt: "^3.0.0"
183
    });
184
    
185
    // Conditional logic based on version
186
    const version = getNuxtVersion();
187
    if (version.startsWith("3.")) {
188
      // Nuxt 3 specific setup
189
    }
190
  }
191
});
192
```
193

194
### Legacy Version Support (Deprecated)
195

196
Deprecated functions for version checking (use `isNuxtMajorVersion` instead).
197

198
```typescript { .api }
199
/**
200
 * Check if running Nuxt 2
201
 * @deprecated Use isNuxtMajorVersion(2) instead
202
 * @param nuxt - Nuxt instance (defaults to current context)
203
 * @returns True if running Nuxt 2
204
 */
205
function isNuxt2(nuxt?: Nuxt): boolean;
206

207
/**
208
 * Check if running Nuxt 3
209
 * @deprecated Use isNuxtMajorVersion(3) instead
210
 * @param nuxt - Nuxt instance (defaults to current context)
211
 * @returns True if running Nuxt 3
212
 */
213
function isNuxt3(nuxt?: Nuxt): boolean;
214
```
215

216
### Advanced Compatibility Patterns
217

218
**Module with Version-Specific Features:**
219

220
```typescript
221
import { 
222
  isNuxtMajorVersion, 
223
  hasNuxtCompatibility,
224
  addComponent 
225
} from "@nuxt/kit";
226

227
export default defineNuxtModule({
228
  meta: {
229
    name: "advanced-module",
230
    compatibility: {
231
      nuxt: ">=3.0.0"
232
    }
233
  },
234
  async setup(options, nuxt) {
235
    // Check if Nuxt 3.5+ for specific features
236
    const hasAdvancedFeatures = await hasNuxtCompatibility({
237
      nuxt: ">=3.5.0"
238
    });
239
    
240
    if (hasAdvancedFeatures) {
241
      // Use newer APIs
242
      addComponent({
243
        name: "AdvancedComponent",
244
        filePath: "~/components/Advanced.vue",
245
        island: true // Islands feature requires 3.5+
246
      });
247
    } else {
248
      // Fallback for older versions
249
      addComponent({
250
        name: "BasicComponent",
251
        filePath: "~/components/Basic.vue"
252
      });
253
    }
254
  }
255
});
256
```
257

258
**Graceful Degradation:**
259

260
```typescript
261
import { 
262
  checkNuxtCompatibility, 
263
  getNuxtVersion,
264
  useLogger 
265
} from "@nuxt/kit";
266

267
export default defineNuxtModule({
268
  async setup(options, nuxt) {
269
    const logger = useLogger("my-module");
270
    const version = getNuxtVersion();
271
    
272
    // Check for ideal version
273
    const idealIssues = await checkNuxtCompatibility({
274
      nuxt: "^3.8.0"
275
    });
276
    
277
    if (idealIssues.length === 0) {
278
      logger.info("Using full feature set");
279
      // Enable all features
280
    } else {
281
      // Check minimum version
282
      const minIssues = await checkNuxtCompatibility({
283
        nuxt: "^3.0.0"
284
      });
285
      
286
      if (minIssues.length === 0) {
287
        logger.warn(`Limited features on Nuxt ${version}`);
288
        // Enable basic features only
289
      } else {
290
        logger.error("Incompatible Nuxt version");
291
        throw new Error("This module requires Nuxt 3.0.0 or higher");
292
      }
293
    }
294
  }
295
});
296
```
297

298
**Environment-Specific Compatibility:**
299

300
```typescript
301
import { 
302
  hasNuxtCompatibility,
303
  isNuxtMajorVersion 
304
} from "@nuxt/kit";
305

306
export default defineNuxtModule({
307
  async setup(options, nuxt) {
308
    // Check Node.js compatibility
309
    const nodeCompat = await hasNuxtCompatibility({
310
      node: ">=18.0.0"
311
    });
312
    
313
    if (!nodeCompat) {
314
      throw new Error("This module requires Node.js 18 or higher");
315
    }
316
    
317
    // Bridge compatibility
318
    if (nuxt.options.bridge && !isNuxtMajorVersion(3)) {
319
      const bridgeCompat = await hasNuxtCompatibility({
320
        bridge: true
321
      });
322
      
323
      if (!bridgeCompat) {
324
        throw new Error("Nuxt Bridge is required for Nuxt 2 compatibility");
325
      }
326
    }
327
  }
328
});
329
```
330

331
**Migration Helper:**
332

333
```typescript
334
import { 
335
  getNuxtVersion,
336
  isNuxtMajorVersion,
337
  useLogger 
338
} from "@nuxt/kit";
339

340
export default defineNuxtModule({
341
  setup(options, nuxt) {
342
    const logger = useLogger("migration-helper");
343
    const version = getNuxtVersion();
344
    
345
    if (isNuxtMajorVersion(2)) {
346
      logger.warn("Nuxt 2 support is deprecated");
347
      logger.info("Please migrate to Nuxt 3 for continued support");
348
      logger.info("Migration guide: https://nuxt.com/docs/migration/overview");
349
    }
350
    
351
    if (version.includes("edge")) {
352
      logger.warn("Using edge version - expect breaking changes");
353
    }
354
  }
355
});
356
```
357

358
## Types
359

360
```typescript { .api }
361
interface VersionInfo {
362
  /** Major version number */
363
  major: number;
364
  /** Minor version number */
365
  minor: number;
366
  /** Patch version number */
367
  patch: number;
368
  /** Pre-release identifier */
369
  prerelease?: string;
370
  /** Build metadata */
371
  build?: string;
372
}
373
```