get-started.md

Getting started

Stylelint is geared towards linting CSS. However, you can extend it to lint other styling languages like SCSS.

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"

Linting other styling languages or libraries

Stylelint can be extended, using the customSyntax option, to:

• parse CSS-like syntaxes like SCSS, Sass, Less and SugarSS
• extract embedded styles from HTML, Markdown and CSS-in-JS object & template literals

For example, to lint SCSS:

1. Use npm to install Stylelint and the postcss-scss syntax:

npm install --save-dev stylelint postcss-scss

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

{
  "customSyntax": "postcss-scss",
  "extends": "stylelint-config-standard"
}

PostCSS syntaxes known to be compatible with Stylelint include:

• postcss-scss
• postcss-less
• postcss-sass
• sugarss

If a PostCSS syntax doesn't exist for your choice of language or CSS-in-JS lribary, please consider creating it and sharing it with the community. It'll need to be compatible with version 8 of PostCSS.

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

{
  "customSyntax": "postcss-scss",
  "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 offical 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 SCSS and SugarSS files:

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

More configs are listed in awesome stylelint.

Customize

Whether you're linting CSS or another styling language, you can further customize Stylelint to your specific needs.

Your configuration

To further customize your Stylelint configuration, you can adapt your:

• rules
• plugins

We recommend you add rules that limit language features to your configuration, e.g. unit-allowed-list, selector-class-pattern 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:

• stylelint-order plugin if you want to order things like properties
• stylelint-csstree-validator plugin if you want 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:

• Node API
• PostCSS plugin

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