stylelint-no-unused-selectors

Concepts

stylelint-no-unused-selectors is a stylelint rule to disallow unused CSS selectors.

It works best with component-oriented applications where views are built on top of a lot of small components, each of which contains a template file (e.g., jsx or tsx) and its corresponding scoped CSS file (e.g., CSS Modules or PostCSS with BEM).

Assuming your component consists of following files:

FooComponent
├── index.js
├── FooComponent.jsx
└── FooComponent.css

when stylelint-no-unused-selectors runs on FooComponent.css, it extracts classes and ids from FooComponent.jsx and detects unused CSS rules.

Features

If you'd like to jump into code, you can find our examples in the repository that are close to real-world situations.

With the built-in plugins, it supports

• HTML via stylelint-no-unused-selectors-plugin-html
• React components written in pure JavaScript, JSX, flow-typed JSX, JSX + future syntaxes in TC39 proposals via stylelint-no-unused-selectors-plugin-jsx
• React components written in TypeScript via stylelint-no-unused-selectors-plugin-tsx
• CSS Modules
• Basic usages of classnames package

See the documentations of built-in plugins for more details.

Installation

yarn add stylelint stylelint-no-unused-selectors

Usage

It works as a stylelint rule, and its plugin name is plugin/no-unused-selectors. An example configuration of stylelint would look like:

{
  "plugins": [
    "stylelint-no-unused-selectors"
  ],
  "rules": {
    "plugin/no-unused-selectors": true
  }
}

See stylelint's documentation for more details.

Configuration

By passing a configuration object described below as the rule's setting value, you can customise the rule's behaviours.

The default configuration is:

{
  "rules": {
    "plugin/no-unused-selectors": {
      "resolve": {
        "documents": [
          "{cssDir}/{cssName}.tsx",
          "{cssDir}/{cssName}.jsx",
          "{cssDir}/{cssName}.html",
          "{cssDir}/{cssName}.htm",
          "{cssDir}/{cssDirName}.tsx",
          "{cssDir}/{cssDirName}.jsx",
          "{cssDir}/{cssDirName}.html",
          "{cssDir}/{cssDirName}.htm",
          "{cssDir}/index.tsx",
          "{cssDir}/index.jsx",
          "{cssDir}/index.html",
          "{cssDir}/index.htm"
        ]
      },
      "plugins": [
        {
          "test": "\\.html?$",
          "plugin": "stylelint-no-unused-selectors-plugin-html"
        },
        {
          "test": "\\.jsx?$",
          "plugin": "stylelint-no-unused-selectors-plugin-jsx",
          "options": {
            "sourceType": "module",
            "plugins": ["jsx", "flow"]
          }
        },
        {
          "test": "\\.tsx$",
          "plugin": "stylelint-no-unused-selectors-plugin-tsx"
        }
      ]
    }
  }
}

resolve.documents

Type: Array<string>

This field tells the rule how to find a template file from a CSS file. The paths are evaluated from the top to the bottom and the first path that exists will be used.

Available variables are as follows:

Name	Description	Example (/project_root/components/Foo/Bar.css)
{cssDir}	The path to a directory that contains a CSS file	/project_root/components/Foo
{cssDirName}	The name of a directory that contains a CSS file	Foo
{cssName}	The file name of a CSS file without its extension	Bar

plugins

Type: Array<Plugin>

stylelint-no-unused-selectors relies on plugins to extract classNames/ids and/or determine if a selector is used in a template file.

Plugin.test

Type: string (the value will be directly compiled with new RegExp())

Plugin.test represents what kind of template files should be processed with a plugin.

Plugin.plugin

Type: string

A name of a plugin that is applied to template files, which is identical to its package name.

Plugin.options

Type: any (optional)

An optional object that will be passed to a plugin, which can be used as parser's configurations or to change the plugin's behaviour. See each plugin's document to know what kind of options are available.

Plugins

Built-in Plugins

• stylelint-no-unused-selectors-plugin-html
• stylelint-no-unused-selectors-plugin-jsx
• stylelint-no-unused-selectors-plugin-tsx

Writing a new plugin

(To be written)

License

The MIT License.

Existing Tools

Please note that all the following tools are to remove unused rules, not to lint CSS files.

• UnCSS uses a similar postcss and jsdom approach, but it can only run on pure HTML code.
• DropCSS has its own HTML and CSS parsers, which contributes to fast and thorough cleanup outputs. It can only run on pure HTML code though.
• PurifyCSS accepts various types of document including HTML, JS and PHP. It has an unique feature that simplifies JS via UglifyJS to extract classNames even if they are constructed dynamically. It detects classNames based on regular expressions, which unfortunately might account for its relatively high false negative rate.
• PurgeCSS is a highly customisable tool thanks to its flexible plugin system. It can run on any kinds of contents as long as there is a plugin.