vite-plugins/config-validator

@lilith/vite-config-validator

Validation tool for Vite configurations to detect anti-patterns and common misconfigurations.

Features

• Validates optimizeDeps configuration (detects exclude anti-pattern)
• Checks for dev version dependencies (-dev. in package.json)
• Validates esbuild plugins structure
• Detects common misconfigurations (hardcoded ports, absolute paths, old ES targets)
• CLI tool for CI/CD integration
• Programmatic API for custom validation workflows

Installation

pnpm add -D @lilith/vite-config-validator

CLI Usage

Basic validation

# Validate default vite.config.ts
npx vite-validate

# Validate specific config file
npx vite-validate vite.config.js

# With options
npx vite-validate --config vite.config.ts --package package.json --verbose

CLI Options

• -c, --config <path> - Path to Vite config file (default: vite.config.ts)
• -p, --package <path> - Path to package.json (default: ./package.json)
• -v, --verbose - Enable verbose output
• -h, --help - Show help message

Exit Codes

• 0 - Validation passed
• 1 - Validation failed with errors

Programmatic Usage

Validate a config object

import { validateViteConfig } from '@lilith/vite-config-validator';

const config = {
  optimizeDeps: {
    exclude: ['some-package'], // Anti-pattern!
  },
};

const result = validateViteConfig(config, './package.json');

if (!result.valid) {
  console.error('Validation errors:', result.errors);
}

if (result.warnings.length > 0) {
  console.warn('Warnings:', result.warnings);
}

Validate a config file

import { validateViteConfigFile } from '@lilith/vite-config-validator';

const result = await validateViteConfigFile('./vite.config.ts', './package.json');

console.log('Valid:', result.valid);
console.log('Errors:', result.errors);
console.log('Warnings:', result.warnings);

Individual validators

import {
  validateOptimizeDeps,
  validateDependencies,
  validateEsbuildPlugins,
  validateCommonMisconfigs,
} from '@lilith/vite-config-validator';

// Validate specific aspects
const optimizeDepsResult = validateOptimizeDeps(config);
const depsResult = validateDependencies('./package.json');
const pluginsResult = validateEsbuildPlugins(config);
const misconfigsResult = validateCommonMisconfigs(config);

Validation Rules

optimizeDeps.exclude (ERROR)

Using optimizeDeps.exclude is an anti-pattern that can cause unexpected bundling behavior. Prefer optimizeDeps.include for explicit control.

// ❌ Bad
{
  optimizeDeps: {
    exclude: ['some-package']
  }
}

// ✅ Good
{
  optimizeDeps: {
    include: ['specific-package']
  }
}

Dev versions (WARNING)

Dependencies with -dev. versions should only be used during active development.

{
  "dependencies": {
    "@lilith/some-package": "1.0.0-dev.1234567890"
  }
}

Hardcoded ports (WARNING)

Hardcoded server ports make configuration inflexible. Use environment variables or @lilith/service-registry.

// ❌ Bad
{
  server: {
    port: 3000
  }
}

// ✅ Good
import { getServiceUrl } from '@lilith/service-registry';

{
  server: {
    port: process.env.PORT || 3000
  }
}

Absolute paths in aliases (WARNING)

Absolute paths in resolve.alias can cause issues across different environments.

// ❌ Bad
{
  resolve: {
    alias: {
      '@': '/absolute/path/to/src'
    }
  }
}

// ✅ Good
import { resolve } from 'path';

{
  resolve: {
    alias: {
      '@': resolve(__dirname, './src')
    }
  }
}

Old ES targets (WARNING)

Very old ES targets (ES5, ES2015) hurt performance. Consider modern targets.

// ❌ Suboptimal
{
  build: {
    target: 'es5'
  }
}

// ✅ Better
{
  build: {
    target: 'es2020'
  }
}

CI/CD Integration

Add to your CI pipeline:

# .forgejo/workflows/validate.yml
- name: Validate Vite config
  run: pnpm vite-validate --config vite.config.ts

Or in package.json scripts:

{
  "scripts": {
    "validate:vite": "vite-validate"
  }
}

TypeScript Types

interface ValidationResult {
  valid: boolean;
  errors: string[];
  warnings: string[];
}

interface ViteConfigLike {
  optimizeDeps?: {
    include?: string[];
    exclude?: string[];
    esbuildOptions?: {
      plugins?: unknown[];
      [key: string]: unknown;
    };
  };
  [key: string]: unknown;
}

interface PackageJsonLike {
  dependencies?: Record<string, string>;
  devDependencies?: Record<string, string>;
  [key: string]: unknown;
}

License

UNLICENSED - Lilith Platform