stylelint-no-undefined-classes

A stylelint plugin that warns when CSS classes used in your HTML/templates are not defined in your CSS files.

Notes

This could probably be a plugin in Biome.js since it's an existing eslint plugin, but since we aren't using Eslint and the Biome plugin ecosystem isn't really ready yet, I made this.

Problem

Have you ever had an HTML element with a class that doesn't exist in your CSS? This can happen when:

• You make a typo in your HTML class name
• You remove a CSS class but forget to update your HTML
• You use a class name thinking it exists in your CSS framework but it doesn't

Normally, stylelint only checks CSS files, not HTML files. This plugin bridges that gap by scanning your HTML files and warning about classes that are used but not defined in your CSS.

Installation

# With npm
npm install --save-dev stylelint-no-undefined-classes

# With yarn
yarn add --dev stylelint-no-undefined-classes

# With pnpm
pnpm add --save-dev stylelint-no-undefined-classes

This plugin requires the following peer dependencies:

• stylelint: >=13.0.0
• node: >=14.0.0

Usage

Add this plugin to your stylelint configuration:

// .stylelintrc.js
module.exports = {
  plugins: ["stylelint-no-undefined-classes"],
  rules: {
    "plugin/no-undefined-classes": true,
  },
};

Options

The plugin accepts the following options:

"plugin/no-undefined-classes": [
  true,
  {
    // Glob patterns to find HTML files to check
    htmlFiles: ["**/*.html", "**/*.vue", "**/*.jsx", "**/*.tsx"],

    // Classes to ignore in the check (won't report even if not defined in CSS)
    ignoreClasses: ["sr-only", "visually-hidden", /^js-/]
  }
]

htmlFiles

An array of glob patterns to find HTML files to check for used classes.

Default: ["**/*.html", "**/*.vue", "**/*.jsx", "**/*.tsx"]

ignoreClasses

An array of class names or regular expressions to ignore. Classes matching these patterns won't be reported even if they aren't defined in your CSS.

Default: []

How It Works

The plugin:

1. Extracts all class selectors defined in your CSS files
2. Finds all HTML files in your project based on the glob patterns
3. Extracts all class names used in those HTML files
4. Reports any class names that are used in HTML but not defined in CSS

Example

Let's say you have the following HTML:

<div class="container">
  <h1 class="title">Hello World</h1>
  <p class="description">Some text here</p>
</div>

And the following CSS:

.container {
  max-width: 1200px;
  margin: 0 auto;
}

.title {
  font-size: 24px;
  font-weight: bold;
}

/* Notice that .description is missing */

The plugin will warn you that the .description class is used in your HTML but not defined in your CSS.

Try the Example

This repository includes an example implementation to demonstrate how the plugin works:

1. Clone this repository
2. Install dependencies:

   npm install

3. Run the example:

   npm run example

This will lint the example CSS files against the example HTML files and report any undefined classes.

Limitations

• The plugin might report false positives for dynamically generated class names
• JavaScript string extraction is basic and might miss complex class name construction
• For large projects, the plugin might increase the linting time due to file scanning

License

MIT