feat(nuxt): allow specifying builder compatibility in modules (#27022)

docs/3.api/5.kit/3.compatibility.md

@@ -25,6 +25,12 @@ async function checkNuxtCompatibility(
 interface NuxtCompatibility {
   nuxt?: string;
   bridge?: boolean;
+  builder?: {
+    // Set `false` if your module is not compatible with a builder
+    // or a semver-compatible string version constraint
+    vite?: false | string;
+    webpack?: false | string;
+  };
 }
 
 interface NuxtCompatibilityIssue {

packages/kit/src/compatibility.ts

@@ -1,4 +1,5 @@
 import satisfies from 'semver/functions/satisfies.js' // npm/node-semver#381
+import { readPackageJSON } from 'pkg-types'
 import type { Nuxt, NuxtCompatibility, NuxtCompatibilityIssues } from '@nuxt/schema'
 import { useNuxt } from './context'
 
@@ -6,6 +7,11 @@ export function normalizeSemanticVersion (version: string) {
   return version.replace(/-[0-9]+\.[0-9a-f]+/, '') // Remove edge prefix
 }
 
+const builderMap = {
+  '@nuxt/vite-builder': 'vite',
+  '@nuxt/webpack-builder': 'webpack',
+}
+
 /**
  * Check version constraints and return incompatibility issues as an array
  */
@@ -40,6 +46,28 @@ export async function checkNuxtCompatibility (constraints: NuxtCompatibility, nu
     }
   }
 
+  // Builder compatibility check
+  if (constraints.builder && typeof nuxt.options.builder === 'string') {
+    const currentBuilder = builderMap[nuxt.options.builder] || nuxt.options.builder
+    if (currentBuilder in constraints.builder) {
+      const constraint = constraints.builder[currentBuilder]!
+      if (constraint === false) {
+        issues.push({
+          name: 'builder',
+          message: `Not compatible with \`${nuxt.options.builder}\`.`,
+        })
+      } else {
+        const builderVersion = await readPackageJSON(nuxt.options.builder, { url: nuxt.options.modulesDir }).then(r => r.version).catch(() => undefined)
+        if (builderVersion && !satisfies(normalizeSemanticVersion(builderVersion), constraint, { includePrerelease: true })) {
+          issues.push({
+            name: 'builder',
+            message: `Not compatible with \`${builderVersion}\` of \`${currentBuilder}\`. This module requires \`${constraint}\`.`,
+          })
+        }
+      }
+    }
+  }
+
   // Allow extending compatibility checks
   await nuxt.callHook('kit:compatibility', constraints, issues)
 

packages/schema/src/types/compatibility.ts

@@ -12,6 +12,29 @@ export interface NuxtCompatibility {
    * - `false`: When using Nuxt 2, using bridge module is not supported.
    */
   bridge?: boolean
+
+  /**
+   * Mark a builder as incompatible, or require a particular version.
+   *
+   * @example
+   * ```ts
+   * export default defineNuxtModule({
+   *   meta: {
+   *     name: 'my-module',
+   *     compatibility: {
+   *       builder: {
+   *         // marking as incompatible
+   *         webpack: false,
+   *         // you can require a (semver-compatible) version
+   *         vite: '^5'
+   *       }
+   *     }
+   *   }
+   *   // ...
+   * })
+   * ```
+   */
+  builder?: Partial<Record<'vite' | 'webpack' | (string & {}), false | string>>
 }
 
 export interface NuxtCompatibilityIssue {