Skip to main content

Getting started

Stylelint is designed for CSS.

However, it can be used with PostCSS syntaxes that:

  • parse CSS-like languages like SCSS, Less and SugarSS
  • extract styles from HTML, JavaScript and Markdown

Linting CSS

1. Use npm to install Stylelint and its standard configuration:

npm install --save-dev stylelint stylelint-config-standard

2. Create a .stylelintrc.json configuration file in the root of your project with the following content:

{
"extends": "stylelint-config-standard"
}

3. Run Stylelint on all the CSS files in your project:

npx stylelint "**/*.css"

If you use a pretty printer alongside Stylelint, you should turn off any conflicting rules. For example, you can use Prettier's shared config to do that:

{
"extends": ["stylelint-config-standard", "stylelint-config-prettier"]
}

Linting everything else

You'll need to use a PostCSS syntax. We recommend extending a shared config that includes the appropriate syntax for your preferred language or library. For example, you can extend the stylelint-config-standard-scss shared config to lint SCSS.

1. Use npm to install Stylelint and the shared config:

npm install --save-dev stylelint stylelint-config-standard-scss

2. Create a .stylelintrc.json configuration file in the root of your project with the following content:

{
"extends": "stylelint-config-standard-scss"
}

3. Run Stylelint on all the SCSS files in your project:

npx stylelint "**/*.scss"

This config includes the postcss-scss syntax, configures the built-in rules for SCSS, and includes the stylelint-scss plugin (a collection of rules specific to SCSS).

If you use Prettier alongside Stylelint, you should use their SCSS shared config:

{
"extends": [
"stylelint-config-standard-scss",
"stylelint-config-prettier-scss"
]
}

If a shared config isn't available for your preferred language or library, then you can install the appropriate PostCSS syntax yourself and use the customSyntax option to configure it.

For example, to lint SugarSS.

1. Use npm to install Stylelint, its standard configuration and the sugarss syntax:

npm install --save-dev stylelint stylelint-config-standard sugarss

2. Create a .stylelintrc.json configuration file in the root of your project with the following content:

{
"extends": "stylelint-config-standard",
"customSyntax": "sugarss"
}

Other PostCSS syntaxes known to be compatible with Stylelint include:

If you lint more than one styling language, then you can use the overrides property. For example, to lint both CSS and SugarSS you can update your configuration object to include:

{
"extends": ["stylelint-config-standard"],
"overrides": [
{
"files": ["**/*.sss"],
"customSyntax": "sugarss",
"rules": {
"block-closing-brace-empty-line-before": null,
"block-closing-brace-newline-after": null,
"block-closing-brace-newline-before": null,
"block-closing-brace-space-before": null,
"block-opening-brace-newline-after": null,
"block-opening-brace-space-after": null,
"block-opening-brace-space-before": null,
"declaration-block-semicolon-newline-after": null,
"declaration-block-semicolon-space-after": null,
"declaration-block-semicolon-space-before": null,
"declaration-block-trailing-semicolon": null
}
}
]
}

Which will extend the official standard config, then use the overrides property to change the custom-syntax and turn off the rules that check braces and semicolons for SugarSS files.

You can then use Stylelint to lint both CSS and SugarSS files:

npx stylelint "**/*.{css,sss}"

More configs are listed in awesome stylelint.

Customize

You can further customize Stylelint to your specific needs.

Your configuration

You can adapt your:

We recommend you add more of the rules that enforce conventions to your configuration, e.g. unit-allowed-list and selector-max-id. These are powerful rules that you can use to enforce non-stylistic consistency in your code.

You can add plugins written by the community to lint more things. For example, you may want to use the stylelint-csstree-validator plugin to validate property and value pairs.

You'll find more plugins listed in awesome stylelint.

Your usage

You don't have to use the Command Line Interface; you can also use the:

There are also integrations for editors, task-runners and others too. Our official extension for Visual Studio Code is a popular choice that lets you see problems inline in your editor.