stylelint-no-unsupported-browser-features

A Stylelint plugin that disallows CSS features that are unsupported by your target browser audience. It uses doiuse for browser compatibility checking against the Can I Use database and integrates with browserslist for flexible browser targeting.

Package Information

• Package Name: stylelint-no-unsupported-browser-features
• Package Type: npm
• Language: JavaScript (ES modules)
• Installation: npm install stylelint-no-unsupported-browser-features

Core Imports

import plugin from "stylelint-no-unsupported-browser-features";

For CommonJS environments:

const plugin = require("stylelint-no-unsupported-browser-features");

Note: The plugin is an ES module ("type": "module" in package.json), but can be imported in CommonJS environments that support ES module imports.

Basic Usage

Add the plugin to your Stylelint configuration:

{
  "plugins": ["stylelint-no-unsupported-browser-features"],
  "rules": {
    "plugin/no-unsupported-browser-features": true
  }
}

With configuration options:

{
  "plugins": ["stylelint-no-unsupported-browser-features"],
  "rules": {
    "plugin/no-unsupported-browser-features": [
      true,
      {
        "browsers": ["> 1%", "Last 2 versions"],
        "ignore": ["rem", "css-table"],
        "ignorePartialSupport": true
      }
    ]
  }
}

Example CSS that would trigger warnings:

/* Triggers warning if targeting IE 8 */
div {
  display: table;
}

/* Triggers warning if targeting older browsers */
.element {
  border-radius: 10px;
}

Architecture

The plugin integrates with Stylelint's standard architecture:

• Plugin Registration: Uses stylelint.createPlugin() for proper integration
• Rule Implementation: Processes PostCSS AST nodes and integrates with doiuse
• Browser Detection: Leverages doiuse library for Can I Use database queries
• Error Reporting: Uses Stylelint's standard reporting mechanism for consistent output
• Configuration: Supports standard Stylelint rule option patterns

Capabilities

Plugin Export

The main plugin export that integrates with Stylelint. This is a function with additional properties attached.

/**
 * Main Stylelint plugin export - a function created by stylelint.createPlugin()
 * @param on - Whether the rule is enabled
 * @param options - Optional configuration for the rule
 * @returns Stylelint rule function
 */
declare function plugin(on: boolean, options?: PluginOptions): StylelintRule;

/**
 * Plugin properties attached to the main function
 */
declare namespace plugin {
  /** The unique identifier for this Stylelint rule */
  const ruleName: "plugin/no-unsupported-browser-features";
  
  /** Message templates for reporting violations */
  const messages: {
    rejected: (details: string) => string;
  };
}

/**
 * Stylelint rule function signature
 */
interface StylelintRule {
  (root: PostCSSRoot, result: StylelintResult): void;
}

/**
 * PostCSS AST root node
 */
interface PostCSSRoot {
  // PostCSS AST root containing CSS nodes
}

/**
 * PostCSS AST node
 */
interface PostCSSNode {
  // PostCSS AST node representing a CSS declaration, rule, etc.
}

/**
 * Stylelint result object for reporting violations
 */
interface StylelintResult {
  // Stylelint result object for rule reporting
}

Plugin Configuration

Configuration options for customizing browser compatibility checks.

interface PluginOptions {
  /** Array of browserslist-compatible browser selectors */
  browsers?: string[];
  /** Array of CSS feature names to ignore */
  ignore?: string[];  
  /** Whether to ignore features with partial browser support */
  ignorePartialSupport?: boolean;
}

browsers - Array of browserslist-compatible strings:

• ["> 1%", "Last 2 versions"] - Modern browser support
• ["IE 8", "Chrome >= 60"] - Specific browser versions
• ["defaults"] - Uses browserslist defaults

ignore - Array of feature names from Can I Use database:

• ["rem", "css-table"] - Ignore specific CSS features
• Feature names are shown in error messages
• Useful for features with known fallbacks

ignorePartialSupport - Boolean flag for partial support handling:

• true - Ignore features that are only partially supported
• false (default) - Report all unsupported features including partial
• Helps reduce noise for features with acceptable partial support

Browser Targeting

The plugin uses browserslist for determining target browsers. Browser lists can be specified in multiple ways:

Via plugin options:

{
  "plugin/no-unsupported-browser-features": [
    true,
    { "browsers": ["> 1%", "Last 2 versions"] }
  ]
}

Via browserslist config file (.browserslistrc):

> 1%
Last 2 versions

Via package.json:

{
  "browserslist": ["> 1%", "Last 2 versions"]
}

Error Reporting

The plugin reports violations using Stylelint's standard error format. Based on the source code, error messages are formatted by the cleanWarningText() internal function and follow this pattern:

interface StylelintViolation {
  ruleName: "plugin/no-unsupported-browser-features";
  message: string; // Format: 'Unexpected browser feature "feature-id" is [support description] (plugin/no-unsupported-browser-features)'
  node: PostCSSNode; // The CSS node causing the violation
  line: number;
  column: number;
}

Actual Message Format Examples from Tests:

• Unexpected browser feature "css-table" is not supported by IE 6 (plugin/no-unsupported-browser-features)
• Unexpected browser feature "rem" is only partially supported by IE 9 (plugin/no-unsupported-browser-features)
• Unexpected browser feature "css-table" is not supported by IE 6,7 (plugin/no-unsupported-browser-features) (multiple browsers)
• Unexpected browser feature "rem" is not supported by IE 7 (plugin/no-unsupported-browser-features) (when ignorePartialSupport removes partial warnings)

Integration with doiuse

The plugin leverages the doiuse library for browser compatibility detection. While this integration is internal, it's important for understanding the plugin's behavior:

// Internal integration details (not directly exposed in public API)
interface DoiuseIntegration {
  /** Options passed to doiuse processor */
  doiuseOptions: {
    browsers?: string[];
    ignore?: string[];
    ignorePartialSupport?: boolean;
    onFeatureUsage: (info: FeatureUsageInfo) => void;
  };
}

interface FeatureUsageInfo {
  usage: PostCSSNode;
  featureData: {
    missing: boolean;  // True if feature is completely unsupported
    partial: boolean;  // True if feature has partial support
  };
}

Processing Flow:

1. Plugin passes configuration options to doiuse
2. doiuse processes the PostCSS AST and identifies unsupported features
3. onFeatureUsage callback tracks feature data for each CSS node
4. doiuse warnings are processed and filtered based on ignorePartialSupport setting
5. Filtered warnings are reported through Stylelint's reporting mechanism

Option Validation

The plugin validates configuration options using Stylelint's built-in validation:

// Internal validation schema (not directly exposed)
interface OptionsValidation {
  /** Validation schema for plugin options */
  optionsSchema: {
    browsers: [(value: any) => boolean];  // Array of functions that check if value is string
    ignore: [(value: any) => boolean];    // Array of functions that check if value is string  
    ignorePartialSupport: (value: any) => boolean;  // Function that checks if value is boolean
  };
}

Validation Behavior:

• If options validation fails, the rule returns early without processing
• browsers and ignore options must be arrays of strings
• ignorePartialSupport must be a boolean value
• Invalid options will cause Stylelint to report configuration errors

Usage Patterns

Development Workflow

Recommended usage with warning-level severity:

{
  "plugins": ["stylelint-no-unsupported-browser-features"],
  "rules": {
    "plugin/no-unsupported-browser-features": [
      true,
      {
        "severity": "warning"
      }
    ]
  }
}

This allows builds to continue while highlighting compatibility issues that may need fallbacks.

CI/CD Integration

For build-breaking compatibility checks:

{
  "plugins": ["stylelint-no-unsupported-browser-features"],
  "rules": {
    "plugin/no-unsupported-browser-features": [
      true,
      {
        "browsers": ["> 1%"],
        "severity": "error"
      }
    ]
  }
}

Feature-Specific Ignoring

To ignore specific features with handled fallbacks:

{
  "plugin/no-unsupported-browser-features": [
    true,
    {
      "ignore": ["rem", "viewport-units", "css-grid"],
      "ignorePartialSupport": true
    }
  ]
}

Dependencies

Peer Dependencies

// Required peer dependency
"stylelint": "^16.0.2"

Direct Dependencies

// Browser compatibility checking
"doiuse": "^6.0.5"

// CSS parsing and processing  
"postcss": "^8.4.32"

Error Handling

The plugin handles various error conditions gracefully:

• Invalid Configuration: Uses Stylelint's validateOptions for option validation
• Missing Browserslist: Falls back to doiuse defaults when no browser list is specified
• Unknown CSS Features: Passes through doiuse warnings without modification
• Partial Support Edge Cases: Properly handles mixed partial/full support violations based on ignorePartialSupport setting

Node.js Requirements

• Minimum Node.js: 18.12.0
• Module Type: ES Module (package.json: "type": "module")
• Export Path: ./lib/index.js