Skip to content

A stylelint rule to catch usage of unknown custom properties

License

Notifications You must be signed in to change notification settings

csstools/stylelint-value-no-unknown-custom-properties

Repository files navigation

Stylelint Value No Unknown Custom Properties stylelint

NPM Version test Discord

Stylelint Value No Unknown Custom Properties is a stylelint rule to disallow usage of unknown custom properties.

Usage

Add stylelint and Stylelint Value No Unknown Custom Properties to your project.

npm install stylelint stylelint-value-no-unknown-custom-properties --save-dev

Add Stylelint Value No Unknown Custom Properties to your stylelint configuration.

{
  "plugins": [
    "stylelint-value-no-unknown-custom-properties"
  ],
  "rules": {
    "csstools/value-no-unknown-custom-properties": true || null
  }
}

Options

true

If the first option is true, then Stylelint Value No Unknown Custom Properties requires all custom properties to be known, and the following patterns are not considered violations:

:root {
  --brand-blue: #33f;
}

.example {
  color: var(--brand-blue);
}
.example {
  color: var(--brand-blue);
}

.some-other-class {
  --brand-blue: #33f;
}
:root {
  --brand-blue: #33f;
  --brand-color: var(--brand-blue);
}

While the following patterns are considered violations:

.example {
  color: var(--brand-blue);
}
:root {
  --brand-color: var(--brand-blue);
}

Custom Properties can be imported using the second option.

null

If the first option is null, then Stylelint Value No Unknown Custom Properties does nothing.


importFrom

When the first option is true, then the second option can specify sources where Custom Properties should be imported from by using an importFrom key. These imports might be CSS, JS, and JSON files, functions, and directly passed objects.

The plugin resolves relative paths from the current working directory which may not work in monorepos, in which case it is best to pass only absolute paths to the plugin.

// .stylelintrc
{
  "plugins": [
    "stylelint-value-no-unknown-custom-properties"
  ],
  "rules": {
    "csstools/value-no-unknown-custom-properties": [true, {
      "importFrom": [
        "path/to/file.css", // => :root { --brand-blue: #33f; }
        "path/to/file.json" // => { "custom-properties": { "--brand-blue": "#33f" } }
      ]
    }]
  }
}

resolver

Use this option to configure how the rule solve paths of @import rules.

// .stylelintrc
{
  "plugins": [
    "stylelint-value-no-unknown-custom-properties"
  ],
  "rules": {
    "csstools/value-no-unknown-custom-properties": [true, {
      "resolver": {
        "extensions": [".css"], // => default to [".css"]
        "paths": ["./assets/css", "./static/css"], // => paths to look for files, default to []
        "moduleDirectories": ["node_modules"] // => modules folder to look for files, default to ["node_modules"]
      }
    }]
  }
}