PostCSS Selector Lint

1.0.2 verified Fri May 01 auth: no javascript

PostCSS Selector Lint is a v1.0.2 PostCSS plugin that warns about disallowed CSS selector types (type, class, id, universal, attribute, pseudo) in global vs local (nested) scope. It helps prevent scope pollution by flagging non-nested type/tag selectors. The configuration is fully customizable per scope. Release cadence is low; latest version is stable. Key differentiator: scope-aware linting (global vs local) rather than simple selector blacklisting. Alternatives like stylelint offer broader linting but require more configuration.

Common errors

error Cannot find module 'postcss-selector-lint' ↓

cause Package not installed or not in node_modules.

fix

Run 'npm install --save-dev postcss-selector-lint' and ensure import path is correct.

error ReferenceError: selectorLint is not defined ↓

cause Incorrect import or variable name mismatch.

fix

Use 'import selectorLint from 'postcss-selector-lint'' (default import) and call as 'postcss([selectorLint(config)])'.

error TypeError: selectorLint is not a function ↓

cause Importing named export instead of default export.

fix

Use default import: 'import selectorLint from 'postcss-selector-lint'.

error Unknown property 'pseudo' encountered in configuration ↓

cause The property name is misspelled in the package; it expects 'psuedo' instead of 'pseudo'.

fix

Change 'pseudo' to 'psuedo' in the configuration object.

Warnings

gotcha Configuration property for pseudo-class selectors is misspelled as 'psuedo' (p-s-u-e-d-o) instead of 'pseudo'. ↓

fix Use property name 'psuedo' in config object.

gotcha Package version 1.0.2 is the latest but there may be no updates since 2020; check for compatibility with PostCSS 8+. ↓

fix Ensure PostCSS version 7 or lower, or verify compatibility. If using PostCSS 8, consider using an alternative like stylelint-scoped-selector.

breaking The package does not support PostCSS 8 natively; it returns warnings but may not work correctly in PostCSS 8+ environments. ↓

fix Use with PostCSS 7, or upgrade to a maintained fork/alternative.

gotcha The 'excludedFiles' option expects an array of strings matching the filename exactly (not glob patterns). ↓

fix Provide exact filenames like 'reset.css' not '*.css'.

deprecated Package uses deprecated PostCSS plugin API (postcss.plugin). ↓

fix If you encounter issues, consider migrating to a stylelint plugin for selector linting.

Install

npm install postcss-selector-lint

yarn add postcss-selector-lint

pnpm add postcss-selector-lint

Imports

default

wrong

const selectorLint = require('postcss-selector-lint')

correct

import selectorLint from 'postcss-selector-lint'

ESM default import; CommonJS require works as this package ships both CJS and ESM.

selectorLint

wrong

import { selectorLint } from 'postcss-selector-lint'

correct

import selectorLint from 'postcss-selector-lint'

Package exports a single function as default, not a named export.

config

wrong

Using incorrect property name 'pseudo' instead of 'psuedo' (typo in package)

correct

import selectorLint from 'postcss-selector-lint'; const config = { global: { type: false, class: true, id: false, universal: false, attribute: false, psuedo: false }, local: { type: true, class: true, id: false, universal: true, attribute: true, psuedo: true }, options: { excludedFiles: [] } }; postcss([selectorLint(config)])

The config property for pseudo-class is misspelled as 'psuedo' (p-s-u-e-d-o). This is a known gotcha.

Quickstart

Sets up PostCSS Selector Lint with a configuration that restricts global selectors to class only, but allows type, universal, and attribute selectors in local scope.

// Install: npm install --save-dev postcss postcss-selector-lint

import postcss from 'postcss';
import selectorLint from 'postcss-selector-lint';

const config = {
    global: {
        type: false,
        class: true,
        id: false,
        universal: false,
        attribute: false,
        psuedo: false,
    },
    local: {
        type: true,
        class: true,
        id: false,
        universal: true,
        attribute: true,
        psuedo: true,
    },
    options: {
        excludedFiles: ['reset.css'],
    },
};

postcss([selectorLint(config)])
    .process('h1 { color: red; }', { from: 'style.css' })
    .then(result => {
        result.warnings().forEach(warn => console.log(warn.toString()));
    });