tessl/npm-nuxt--schema

Nuxt types and default configuration providing comprehensive TypeScript types, schema definitions, and configuration system for the Nuxt framework.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Compatibility System

Name: tessl/npm-nuxt--schema
Author: tessl

The compatibility system in @nuxt/schema provides module compatibility checking and validation to ensure proper module integration with specific Nuxt versions and build systems.

Core Compatibility Types

NuxtCompatibility Interface

Defines compatibility requirements for modules and packages.

interface NuxtCompatibility {
  /** Required Nuxt version in semver format */
  nuxt?: string
  /** Builder compatibility requirements */
  builder?: Partial<Record<'vite' | 'webpack' | 'rspack' | (string & {}), false | string>>
}

Compatibility Issues

Types for handling and reporting compatibility issues.

interface NuxtCompatibilityIssue {
  name: string
  message: string
}

interface NuxtCompatibilityIssues extends Array<NuxtCompatibilityIssue> {
  /** Return formatted error message */
  toString(): string
}

Compatibility Declaration

Module Compatibility

import type { NuxtModule, NuxtCompatibility } from '@nuxt/schema';

const myModule: NuxtModule = {
  meta: {
    name: 'my-module',
    version: '2.0.0',
    compatibility: {
      // Require Nuxt 3.2.0 or higher
      nuxt: '^3.2.0',
      
      // Builder-specific compatibility
      builder: {
        vite: '^4.0.0',      // Require Vite 4.0.0+
        webpack: '^5.0.0',   // Require Webpack 5.0.0+
        rspack: false        // Not compatible with Rspack
      }
    } satisfies NuxtCompatibility
  },
  
  setup(options, nuxt) {
    // Module setup - compatibility is checked before this runs
  }
};

Advanced Compatibility Requirements

const advancedModule: NuxtModule = {
  meta: {
    name: 'advanced-module',
    compatibility: {
      // Require specific Nuxt version range
      nuxt: '>=3.8.0 <4.0.0',
      
      // Complex builder requirements
      builder: {
        vite: '^5.0.0',         // Latest Vite
        webpack: '>=5.88.0',    // Minimum Webpack version
        rspack: '^1.0.0'        // Rspack support
      }
    }
  },
  
  setup(options, nuxt) {
    // Check for additional runtime compatibility
    if (nuxt.options.ssr === false && !options.spaMode) {
      throw new Error('This module requires SSR or explicit SPA mode configuration');
    }
  }
};

Compatibility Checking

Automatic Compatibility Validation

Nuxt automatically validates module compatibility during installation:

// This validation happens automatically
export default defineNuxtConfig({
  modules: [
    // ✅ Compatible module
    ['my-compatible-module', { /* options */ }],
    
    // ❌ Would throw compatibility error if requirements not met
    ['incompatible-module', { /* options */ }]
  ]
});

Manual Compatibility Checking

import type { NuxtCompatibility, NuxtCompatibilityIssues } from '@nuxt/schema';

function checkCompatibility(
  compatibility: NuxtCompatibility,
  nuxtVersion: string,
  builderName: string,
  builderVersion: string
): NuxtCompatibilityIssues {
  const issues: NuxtCompatibilityIssues = [] as any;
  
  // Check Nuxt version compatibility
  if (compatibility.nuxt) {
    if (!satisfies(nuxtVersion, compatibility.nuxt)) {
      issues.push({
        name: 'nuxt-version',
        message: `Requires Nuxt ${compatibility.nuxt}, but found ${nuxtVersion}`
      });
    }
  }
  
  // Check builder compatibility
  if (compatibility.builder) {
    const builderReq = compatibility.builder[builderName];
    
    if (builderReq === false) {
      issues.push({
        name: 'builder-incompatible',
        message: `Not compatible with ${builderName}`
      });
    } else if (builderReq && !satisfies(builderVersion, builderReq)) {
      issues.push({
        name: 'builder-version',
        message: `Requires ${builderName} ${builderReq}, but found ${builderVersion}`
      });
    }
  }
  
  // Add toString method
  issues.toString = function() {
    return this.map(issue => `- ${issue.message}`).join('\n');
  };
  
  return issues;
}

Compatibility Hook Integration

export default defineNuxtModule({
  meta: {
    name: 'compatibility-aware-module'
  },
  
  setup(options, nuxt) {
    // Listen for compatibility checks
    nuxt.hook('kit:compatibility', (compatibility, issues) => {
      console.log('Compatibility check:', compatibility);
      
      if (issues.length > 0) {
        console.warn('Compatibility issues found:', issues.toString());
      }
    });
    
    // Perform custom compatibility checks
    const customCompatibility: NuxtCompatibility = {
      nuxt: '^3.0.0',
      builder: {
        vite: '^4.0.0'
      }
    };
    
    const issues = checkCompatibility(
      customCompatibility,
      nuxt.options._nuxtVersion || '3.0.0',
      nuxt.options.builder === '@nuxt/vite-builder' ? 'vite' : 'webpack',
      '4.0.0' // Would normally detect actual version
    );
    
    if (issues.length > 0) {
      nuxt.callHook('kit:compatibility', customCompatibility, issues);
    }
  }
});

Builder-Specific Compatibility

Vite-Only Modules

const viteOnlyModule: NuxtModule = {
  meta: {
    name: 'vite-only-module',
    compatibility: {
      nuxt: '^3.0.0',
      builder: {
        vite: '^4.0.0',
        webpack: false,   // Explicitly not compatible
        rspack: false     // Explicitly not compatible
      }
    }
  },
  
  setup(options, nuxt) {
    // This will only run with Vite builder
    if (nuxt.options.builder !== '@nuxt/vite-builder') {
      throw new Error('This module requires Vite builder');
    }
  }
};

Multi-Builder Support

const multiBuiderModule: NuxtModule = {
  meta: {
    name: 'multi-builder-module',
    compatibility: {
      nuxt: '^3.0.0',
      builder: {
        vite: '^4.0.0',
        webpack: '^5.0.0',
        rspack: '^1.0.0'
      }
    }
  },
  
  setup(options, nuxt) {
    // Different setup based on builder
    if (nuxt.options.builder === '@nuxt/vite-builder') {
      // Vite-specific setup
      nuxt.hook('vite:extend', ({ config }) => {
        config.plugins = config.plugins || [];
        config.plugins.push(myVitePlugin());
      });
    } else if (nuxt.options.builder === '@nuxt/webpack-builder') {
      // Webpack-specific setup
      nuxt.hook('webpack:config', (configs) => {
        configs.forEach(config => {
          config.plugins = config.plugins || [];
          config.plugins.push(new MyWebpackPlugin());
        });
      });
    }
  }
};

Feature-Based Compatibility

Experimental Feature Dependencies

const experimentalModule: NuxtModule = {
  meta: {
    name: 'experimental-module',
    compatibility: {
      nuxt: '^3.8.0' // Requires newer Nuxt for experimental features
    }
  },
  
  setup(options, nuxt) {
    // Check for required experimental features
    if (!nuxt.options.experimental?.componentIslands) {
      throw new Error('This module requires experimental.componentIslands to be enabled');
    }
    
    if (!nuxt.options.experimental?.typedPages) {
      console.warn('This module works best with experimental.typedPages enabled');
    }
  }
};

Runtime Compatibility Checks

const runtimeCompatibleModule: NuxtModule = {
  setup(options, nuxt) {
    // Check Node.js version
    const nodeVersion = process.version;
    const requiredNodeVersion = '>=18.0.0';
    
    if (!satisfies(nodeVersion, requiredNodeVersion)) {
      throw new Error(`Requires Node.js ${requiredNodeVersion}, found ${nodeVersion}`);
    }
    
    // Check for required dependencies
    const requiredDeps = ['@vue/composition-api', 'pinia'];
    
    for (const dep of requiredDeps) {
      try {
        require.resolve(dep);
      } catch {
        throw new Error(`Missing required dependency: ${dep}`);
      }
    }
    
    // Environment compatibility
    if (nuxt.options.nitro?.preset === 'cloudflare-pages' && options.useFileSystem) {
      throw new Error('File system operations not supported on Cloudflare Pages');
    }
  }
};

Compatibility Utilities

Version Checking Helper

import semver from 'semver';

export function createCompatibilityChecker() {
  return {
    checkNuxtVersion(required: string, actual: string): boolean {
      return semver.satisfies(actual, required);
    },
    
    checkBuilderVersion(
      builderName: string,
      required: string | false,
      actual: string
    ): boolean {
      if (required === false) return false;
      if (!required) return true;
      return semver.satisfies(actual, required);
    },
    
    formatCompatibilityMessage(
      moduleName: string,
      issues: NuxtCompatibilityIssue[]
    ): string {
      if (issues.length === 0) return '';
      
      return `
Module "${moduleName}" has compatibility issues:
${issues.map(issue => `- ${issue.message}`).join('\n')}

Please check the module documentation for supported versions.
      `.trim();
    }
  };
}

Compatibility Warning System

export function createCompatibilityWarningSystem(nuxt: Nuxt) {
  const warnings = new Set<string>();
  
  return {
    warn(moduleName: string, message: string) {
      const key = `${moduleName}:${message}`;
      if (warnings.has(key)) return;
      
      warnings.add(key);
      console.warn(`[${moduleName}] ${message}`);
    },
    
    checkAndWarn(
      moduleName: string,
      compatibility: NuxtCompatibility,
      context: {
        nuxtVersion: string,
        builderName: string,
        builderVersion: string
      }
    ) {
      const issues = checkCompatibility(
        compatibility,
        context.nuxtVersion,
        context.builderName,
        context.builderVersion
      );
      
      issues.forEach(issue => {
        this.warn(moduleName, issue.message);
      });
      
      return issues.length === 0;
    }
  };
}

The compatibility system ensures that modules work correctly with specific Nuxt versions and build configurations, providing clear error messages and warnings when compatibility issues are detected.

Install with Tessl CLI