Stylelint Webpack Plugin

npm install stylelint --save-dev

const StylelintPlugin = require('stylelint-webpack-plugin');

import StylelintWebpackPlugin = require('stylelint-webpack-plugin');

const StylelintPlugin = require('stylelint-webpack-plugin');

module.exports = {
  // ...
  plugins: [
    new StylelintPlugin({
      files: ['src/**/*.{css,scss,sass}'],
      fix: true,
    }),
  ],
  // ...
};

class StylelintWebpackPlugin {
  /**
   * Creates a new Stylelint webpack plugin instance
   * @param options - Plugin configuration options
   */
  constructor(options?: Options);
  
  /**
   * Webpack plugin apply method - integrates with webpack compilation hooks
   * @param compiler - Webpack compiler instance
   */
  apply(compiler: Compiler): void;
}

interface Options extends Partial<PluginOptions & StylelintOptions> {}

interface PluginOptions {
  /** Root directory for files (default: webpack context) */
  context: string;
  /** Emit errors to webpack compilation (default: true) */
  emitError: boolean;
  /** Emit warnings to webpack compilation (default: true) */
  emitWarning: boolean;
  /** Files/directories to exclude (default: ['**/node_modules/**', output.path]) */
  exclude?: string | string[];
  /** File extensions to check (default: ['css', 'scss', 'sass']) */
  extensions: string | string[];
  /** Fail build on errors (default: true) */
  failOnError: boolean;
  /** Fail build on warnings (default: false) */
  failOnWarning: boolean;
  /** Files/directories/globs to lint (required for plugin to work) */
  files: string | string[];
  /** Output formatter for results */
  formatter: FormatterType;
  /** Lint only changed files, skip full lint on start (default: false) */
  lintDirtyModulesOnly: boolean;
  /** Process errors only, ignore warnings (default: false) */
  quiet: boolean;
  /** Path to stylelint instance (default: 'stylelint') */
  stylelintPath: string;
  /** Write output report to file */
  outputReport: OutputReport;
  /** Enable multi-threading: true=auto, number=pool size, false/undefined=disabled (default: false) */
  threads?: number | boolean;
}

interface OutputReport {
  /** Output file path (relative to webpack output.path) */
  filePath?: string;
  /** Formatter for output file (defaults to main formatter) */
  formatter?: FormatterType;
}

type FormatterType = string | ((results: LintResult[]) => string) | Promise<(results: LintResult[]) => string>;

// Basic configuration
new StylelintPlugin({
  files: ['src/**/*.{css,scss}'],
});

// Advanced configuration
new StylelintPlugin({
  context: './src',
  files: ['**/*.{css,scss,sass}'],
  exclude: ['vendor/**', 'legacy/**'],
  fix: true,
  cache: true,
  threads: true,
  failOnError: true,
  failOnWarning: false,
  formatter: 'json',
  outputReport: {
    filePath: 'stylelint-report.json',
    formatter: 'json'
  }
});

// Quiet mode (errors only)
new StylelintPlugin({
  files: ['src/**/*.scss'],
  quiet: true,
  emitWarning: false
});

interface StylelintOptions {
  /** Use cache to store results (default: true) */
  cache?: boolean;
  /** Cache location (default: 'node_modules/.cache/stylelint-webpack-plugin/.stylelintcache') */
  cacheLocation?: string;
  /** Configuration object (overrides config files) */
  config?: Config;
  /** Path to configuration file */
  configFile?: string;
  /** Base directory for configuration file resolution */
  configBasedir?: string;
  /** Configuration basename - resolves config relative to this */
  configBasename?: string;
  /** Custom syntax module */
  customSyntax?: string;
  /** Enable processing when no input files */
  allowEmptyInput?: boolean;
  /** Globby options for file pattern matching */
  globbyOptions?: object;
  /** Auto-fix problems where possible */
  fix?: boolean;
  /** Ignore .stylelintignore files */
  ignorePath?: string;
  /** Pattern of files to ignore */
  ignorePattern?: string[];
  /** Ignore disable comments */
  ignoreDisables?: boolean;
  /** Report needless disable comments */
  reportNeedlessDisables?: boolean;
  /** Report invalid scope disable comments */
  reportInvalidScopeDisables?: boolean;
  /** Report descending specificity errors */
  reportDescriptionlessDisables?: boolean;
  /** Maximum allowed warnings before failing */
  maxWarnings?: number;
  /** Disable default ignores */
  disableDefaultIgnores?: boolean;
  /** Enable/disable rules based on globs */
  overrides?: OverrideConfig[];
}

/**
 * Process and validate plugin options with defaults
 * @param pluginOptions - User-provided options
 * @returns Processed plugin options with defaults applied
 */
function getOptions(pluginOptions: Options): Partial<PluginOptions>;

/**
 * Extract stylelint-specific options from combined options
 * @param pluginOptions - Combined plugin and stylelint options  
 * @returns Stylelint-only options for passing to stylelint
 */
function getStylelintOptions(pluginOptions: Options): Partial<StylelintOptions>;

class StylelintError extends Error {
  /**
   * Creates a stylelint-specific error
   * @param messages - Error message content
   */
  constructor(messages?: string);
  
  /** Error name identifier */
  name: string;
  /** Empty stack trace (errors come from stylelint) */
  stack: string;
}

new StylelintPlugin({
  files: ['src/**/*.scss'],
  threads: true,     // Auto-detect CPU count
  // or
  threads: 4,        // Explicit thread count
  // or  
  threads: false     // Disable threading
});

new StylelintPlugin({
  files: ['src/**/*.css'],
  stylelintPath: './custom-stylelint',
  config: {
    rules: {
      'color-no-invalid-hex': true,
      'declaration-colon-space-after': 'always'
    }
  }
});

new StylelintPlugin({
  files: ['src/**/*.scss'],
  lintDirtyModulesOnly: true  // Only lint changed files in watch mode
});

type Compiler = import('webpack').Compiler;
type LintResult = import('stylelint').LintResult;
type LinterResult = import('stylelint').LinterResult;
type LinterOptions = import('stylelint').LinterOptions;
type Formatter = import('stylelint').Formatter;

/** Stylelint configuration object */
interface Config {
  /** Rules configuration */
  rules?: { [ruleName: string]: any };
  /** Plugins to load */
  plugins?: string[];
  /** Extends configuration */
  extends?: string | string[];
  /** Ignore patterns */
  ignoreFiles?: string | string[];
  /** Default severity */
  defaultSeverity?: 'error' | 'warning';
  /** Custom syntax */
  customSyntax?: string;
}

/** Override configuration for specific patterns */
interface OverrideConfig {
  /** Files pattern to match */
  files: string | string[];
  /** Rules to apply for matched files */
  rules?: { [ruleName: string]: any };
  /** Custom syntax for matched files */
  customSyntax?: string;
}