tessl/npm-stylelint

A mighty CSS linter that helps you avoid errors and enforce conventions.

—

Pending

Overview

Eval results

Files

Configuration

Name: tessl/npm-stylelint
Author: tessl

Comprehensive configuration system supporting extends, plugins, rule settings, file-specific overrides, and complex linting scenarios. Enables both simple setup for common use cases and sophisticated configuration for enterprise environments.

Capabilities

Configuration Object

Main configuration interface supporting all Stylelint options and settings.

interface Config {
  /** Extend existing configurations */
  extends?: string | string[];
  /** Load plugins for custom rules */
  plugins?: (string | Plugin)[];
  /** Internal plugin functions map */
  pluginFunctions?: { [pluginName: string]: Rule };
  /** Files to ignore during linting */
  ignoreFiles?: string | string[];
  /** Ignore patterns for inline matching */
  ignorePatterns?: string;
  /** Rule configuration object */
  rules?: { [ruleName: string]: ConfigRuleSettings<any, Object> };
  /** File-specific configuration overrides */
  overrides?: ConfigOverride[];
  /** Custom syntax for non-CSS files */
  customSyntax?: CustomSyntax;
  /** Output formatter configuration */
  formatter?: FormatterType | Formatter;
  /** Default severity for rules without explicit severity */
  defaultSeverity?: 'warning' | 'error';
  /** Ignore disable comments */
  ignoreDisables?: boolean;
  /** Report unnecessary disable comments */
  reportNeedlessDisables?: DisableSettings;
  /** Report invalid scope disable comments */
  reportInvalidScopeDisables?: DisableSettings;
  /** Report disable comments without descriptions */
  reportDescriptionlessDisables?: DisableSettings;
  /** Report unscoped disable comments */
  reportUnscopedDisables?: DisableSettings;
  /** Custom configuration comment prefix */
  configurationComment?: string;
  /** Automatically fix problems where possible */
  fix?: boolean;
  /** Compute edit info for fixes */
  computeEditInfo?: boolean;
  /** Enable result caching for performance */
  cache?: boolean;
  /** Only report errors, ignore warnings */
  quiet?: boolean;
  /** Allow empty input without failing */
  allowEmptyInput?: boolean;
  /** Validate rule options */
  validate?: boolean;
  /** Functions for hooking into Stylelint's pipeline (experimental) */
  processors?: string[];
  /** Language-specific options */
  languageOptions?: LanguageOptions;
}

Configuration Resolution

Resolve effective configuration for specific files, accounting for extends, overrides, and file-specific settings.

/**
 * Resolve the effective configuration for a given file
 * @param filePath - Path to the file to resolve config for
 * @param options - Options for config resolution
 * @returns Promise resolving to config or undefined if no config found
 */
function resolveConfig(
  filePath: string,
  options?: {
    cwd?: string;
    config?: Config;
    configBasedir?: string;
    configFile?: string;
  }
): Promise<Config | undefined>;

Usage Examples:

import { resolveConfig } from "stylelint";

// Resolve config for specific file
const config = await resolveConfig("./src/styles/main.css");

// Resolve with custom options
const customConfig = await resolveConfig("./src/styles/main.scss", {
  cwd: process.cwd(),
  configFile: ".stylelintrc.custom.json"
});

// Check if file has configuration
if (config) {
  console.log("Rules:", config.rules);
  console.log("Extends:", config.extends);
}

Extending Configurations

Extend existing configurations from npm packages, files, or built-in presets.

type ConfigExtends = string | string[];

// Configuration examples
const extendsConfig = {
  extends: [
    "stylelint-config-standard",
    "stylelint-config-sass-guidelines",
    "./custom-rules.js"
  ],
  rules: {
    // Override or add rules
    "color-hex-length": "short"
  }
};

Rule Configuration

Configure individual rules with primary options, secondary options, and severity levels.

type ConfigRuleSettings<T, O extends Object> = 
  | null                    // Disable rule
  | undefined              // Default/inherited
  | NonNullable<T>         // Primary option
  | [NonNullable<T>]       // Primary option in array
  | [NonNullable<T>, O];   // Primary + secondary options

// Rule configuration examples
const rulesConfig = {
  rules: {
    // Simple boolean rule
    "color-no-invalid-hex": true,
    
    // Rule with primary option
    "color-hex-length": "short",
    
    // Rule with secondary options
    "property-no-unknown": [true, { 
      ignoreProperties: ["composes"],
      checkPrefixed: true 
    }],
    
    // Rule with severity override
    "font-weight-notation": [
      "numeric", 
      { severity: "error" }
    ],
    
    // Disabled rule
    "selector-max-id": null
  }
};

File-Specific Overrides

Apply different configurations to specific files or file patterns.

interface ConfigOverride {
  /** File patterns this override applies to */
  files: string | string[];
  /** Optional name for the override */
  name?: string;
  /** Override configuration (same as Config except no overrides) */
  extends?: ConfigExtends;
  plugins?: (string | Plugin)[];
  rules?: { [ruleName: string]: ConfigRuleSettings<any, Object> };
  customSyntax?: CustomSyntax;
  ignoreFiles?: string | string[];
  defaultSeverity?: 'warning' | 'error';
  ignoreDisables?: boolean;
}

// Override examples
const overrideConfig = {
  rules: {
    "color-hex-length": "short"
  },
  overrides: [
    {
      files: ["**/*.scss"],
      customSyntax: "postcss-scss",
      rules: {
        "at-rule-no-unknown": [true, { 
          ignoreAtRules: ["include", "mixin", "extend"] 
        }]
      }
    },
    {
      files: ["src/legacy/**/*.css"],
      rules: {
        "property-no-vendor-prefix": null,
        "selector-max-id": null
      }
    }
  ]
};

Plugin Configuration

Load and configure custom plugins for additional rules and functionality.

type ConfigPlugins = string | Plugin | (string | Plugin)[];

interface Plugin {
  ruleName: string;
  rule: Rule;
}

// Plugin configuration
const pluginConfig = {
  plugins: [
    "stylelint-scss",
    "stylelint-order", 
    "@stylelint/postcss-css-in-js"
  ],
  rules: {
    // Plugin rules
    "scss/at-rule-no-unknown": true,
    "order/properties-alphabetical-order": true,
    "css-in-js/no-unused-styles": "error"
  }
};

Disable Comments Configuration

Configure how disable comments work and are reported.

interface DisableSettings {
  except?: (string | RegExp)[];
  severity?: 'warning' | 'error';
}

const disableConfig = {
  // Report unnecessary disable comments
  reportNeedlessDisables: true,
  
  // Report disable comments without descriptions
  reportDescriptionlessDisables: [true, { 
    severity: "error" 
  }],
  
  // Report disable comments with invalid scope
  reportInvalidScopeDisables: true,
  
  // Custom configuration comment prefix
  configurationComment: "stylelint-custom"
};

Custom Syntax Support

Configure custom syntaxes for processing non-standard CSS files.

type CustomSyntax = string | PostCSS.Syntax;

const syntaxConfig = {
  overrides: [
    {
      files: ["**/*.scss"],
      customSyntax: "postcss-scss"
    },
    {
      files: ["**/*.less"],
      customSyntax: "postcss-less"
    },
    {
      files: ["**/*.js", "**/*.jsx"],
      customSyntax: "@stylelint/postcss-css-in-js"
    }
  ]
};

Configuration File Formats

Stylelint supports multiple configuration file formats and loading strategies.

// .stylelintrc.json
{
  "extends": "stylelint-config-standard",
  "rules": {
    "color-hex-length": "short"
  }
}

// .stylelintrc.js
module.exports = {
  extends: "stylelint-config-standard",
  rules: {
    "color-hex-length": "short"
  }
};

// package.json
{
  "stylelint": {
    "extends": "stylelint-config-standard",
    "rules": {
      "color-hex-length": "short"
    }
  }
}

// stylelint.config.js
export default {
  extends: "stylelint-config-standard",
  rules: {
    "color-hex-length": "short"
  }
};

Complete Configuration Example

const complexConfig = {
  extends: [
    "stylelint-config-standard-scss",
    "stylelint-config-prettier"
  ],
  
  plugins: [
    "stylelint-scss",
    "stylelint-order",
    "stylelint-declaration-block-no-ignored-properties"
  ],
  
  defaultSeverity: "warning",
  
  ignoreFiles: [
    "node_modules/**/*",
    "dist/**/*",
    "coverage/**/*"
  ],
  
  rules: {
    // Color rules
    "color-hex-length": "short",
    "color-no-invalid-hex": true,
    
    // SCSS-specific rules
    "scss/at-rule-no-unknown": true,
    "scss/dollar-variable-pattern": "^[a-z][a-zA-Z0-9]*$",
    
    // Order rules
    "order/properties-alphabetical-order": true,
    
    // Custom severity
    "selector-max-id": ["error", 0]
  },
  
  overrides: [
    {
      files: ["**/*.scss"],
      customSyntax: "postcss-scss"
    },
    {
      files: ["src/legacy/**/*.css"],
      rules: {
        "property-no-vendor-prefix": null,
        "selector-max-specificity": null
      }
    }
  ],
  
  reportNeedlessDisables: true,
  reportInvalidScopeDisables: true,
  reportDescriptionlessDisables: [true, { severity: "error" }]
};

Install with Tessl CLI