stylelint

What is stylelint?

Stylelint is a powerful, modern linter that helps you avoid errors and enforce consistent conventions in your stylesheets. It is configurable and supports the latest CSS syntax as well as CSS-like syntaxes, such as SCSS.

What are stylelint's main functionalities?

Linting CSS files

This command will lint all CSS files in the 'src' directory and its subdirectories. It will check for errors and code quality issues based on the rules defined in the configuration.

"stylelint 'src/**/*.css'"

Fixing CSS files

This command will not only lint the CSS files but also attempt to fix any fixable issues, such as formatting inconsistencies, automatically.

"stylelint 'src/**/*.css' --fix"

Custom configuration

This JSON represents a custom Stylelint configuration object where specific rules are defined, such as disallowing invalid hex colors, setting indentation preferences, and enforcing no leading zero for numbers.

{ "rules": { "color-no-invalid-hex": true, "indentation": [2, { "except": ["block"] }], "number-leading-zero": "never" } }

Extending configurations

This JSON represents a Stylelint configuration that extends a shared configuration, in this case, 'stylelint-config-standard', which is a popular set of rules that enforce common stylistic conventions.

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

Using plugins

This JSON represents a Stylelint configuration that includes a plugin, 'stylelint-scss', which adds SCSS-specific linting rules to Stylelint. The configuration then enables a rule from that plugin to disallow unknown at-rules in SCSS.

{ "plugins": ["stylelint-scss"], "rules": { "scss/at-rule-no-unknown": true } }

Other packages similar to stylelint

eslint

ESLint is a static code analysis tool for identifying problematic patterns in JavaScript code. It is similar to Stylelint in its extensibility and plugin ecosystem but is focused on JavaScript rather than stylesheets.

prettier

Prettier is an opinionated code formatter that supports many languages, including CSS. Unlike Stylelint, which can both lint and fix code, Prettier is solely focused on code formatting and does not provide linting functionalities.

sass-lint

Sass-lint is a node-only Sass linter for both sass and scss syntax. It is similar to Stylelint when working with SCSS files but does not support plain CSS or other CSS-like syntaxes.

csslint

CSSLint is a tool that helps to point out problems with your CSS code. It is less configurable than Stylelint and has a smaller set of rules and plugins, but it serves a similar purpose in linting CSS files.

README

stylelint

A mighty, modern CSS linter that helps you enforce consistent conventions and avoid errors in your stylesheets.

Features

• Over one hundred and fifty rules: Including those that:
  • Catch errors: e.g. invalid hex colors, indistinguishable colors, or overriding shorthand properties.
  • Enforce best practices: e.g. keeping specificity low or disallowing vendor prefixes in your source code.
  • Control what languages features can be used: e.g. whitelisting specific units, properties and functions, or disallowing certain selector types.
  • Enforce code style conventions: e.g. checking the spacing around the colon in declarations or specifying patterns for class selectors.
• Support for the latest CSS syntax: Including custom properties, range context for media features, calc() and nesting.
• Understands CSS-like syntaxes: The linter is powered by PostCSS, so it understands any syntax that PostCSS can parse, including SCSS, SugarSS, and experimental support for Less.
• Completely unopinionated: Only enable the rules you want, and configure them with options that tailor the linter to your needs.
• Support for plugins: It's easy to create your own rules and add them to the linter.
• Automatically fix some stylistic warnings: By using stylefmt which supports stylelint configuration files.
• Shareable configs: If you don't want to craft your own config, you can extend a shareable config.
• Options validator: So that you can be confident that your config is valid.
• Well tested: Nearly twenty five thousand tests cover the internals and rules.
• Growing community: Used by Facebook, Github, Wikimedia, GSA, and WordPress among others.

Example output

Getting started

With stylelint, it's easy to start linting your CSS:

1. Decide how you want to use stylelint:
   • via the stylelint CLI
   • via a plugin for your build tool (gulp, webpack etc)
   • via a plugin for your text editor (atom, sublime text etc)
   • via the stylelint Node API
   • via the stylelint PostCSS plugin
2. Create your configuration object by either extending a shared config or crafting your own:
   • To extend a shared config, we recommend using stylelint-config-standard. It includes over 80 of stylelint's rules with sensible defaults. (You can always override specific rules after extending the config.) We update the config with each new release of stylelint. Alternately, you can search for a community config and extend that instead.
   • To craft your own config, first learn about how rules are named and how they work together, then either:
     • Start small and only learn about the rules you want to turn on and enforce. All of the rules are off by default, and so you can start small, growing your config over time as you have a chance to explore more of the rules.
     • Or copy-paste this example configuration, which lists all of stylelint's rules and their primary options. Then you can edit the options of each rule to your liking, and remove (or turn off with null) the rules that you don't care to enforce.
3. Lint!

Guides

You'll find more detailed information on using stylelint and tailoring it to your needs in our guides:

• User guide - Usage, configuration, FAQ and complementary tools.
• Developer guide - Contributing to stylelint and writing your own plugins & formatters.

Need help?

If you're looking for help or have a support question, then check out our FAQ first. If the answer to your problem isn't there, then go to stackoverflow. stackoverflow is a huge Question and Answer community, and tagging your post there with "stylelint" will catch the stylelint team's attention.

If you think you've found a bug or if you have feature request, then create a new GitHub issue. Be sure to follow the issue template, answering each question, as this helps us greatly in understanding your problem or request.

Upgrading? Please read our CHANGELOG to learn what changes to expect in the latest version, whether that's new features, bug fixes, renamed rules, or whatever else.

Help out

There is always a lot of work to do, and already well over 150 rules to maintain. So please help out in any way that you can:

• Chime in on any open issue or pull request.
• Create, enhance, and debug rules (see our guide to "Working on rules").
• Improve documentation.
• Add new tests to absolutely anything.
• Work on improving performance of rules.
• Open new issues about your ideas for making stylelint better, and pull requests to show us how your idea works.
• Create or contribute to ecosystem tools, like the plugins for Atom and Sublime Text.

License

Changelog

7.8.0

• Deprecated: 15 rules (#2197, #2285 & #2309).
  • block-no-single-line. Use block-opening-brace-newline-after and block-closing-brace-newline-before rules with the option "always" instead.
  • declaration-block-properties-order. Use the stylelint-order plugin pack instead.
  • rule-nested-empty-line-before and rule-non-nested-empty-line-before. Use the new rule-empty-line-before rule instead.
  • time-no-imperceptible. Use the new time-min-milliseconds rule with 100 as its primary option.
  • It is beyond the scope of Stylelint's core package to effectively validate against the CSS spec. Please investigate csstree and css-values for this functionality, and contribute to those projects and to Stylelint plugins wrapping them. csstree already has a Stylelint plugin, and css-values needs one to be developed. The following rules are deprecated for this reason.
    • media-feature-no-missing-punctuation.
    • selector-no-empty.
  • A plugin is a better package for a rule that wraps a third-party library. The following rules are deprecated for this reason. We encourage users to create and help maintain plugins for these rules.
    • no-browser-hacks
    • no-indistinguishable-colors
    • no-unsupported-browser-features
  • The following rules did not seem useful. If you liked these rules, please create plugins for them.
    • custom-property-no-outside-root
    • root-no-standard-properties
    • selector-root-no-composition.
  • The following rules did not work well.
    • stylelint-disable-reason could not enforce providing a reason.
    • declaration-block-no-ignored-properties could not reliably account for replaced elements.
• Deprecated: 4 options (#2213).
  • "all-nested" option for at-rule-empty-line-before. Use the "inside-block" option instead.
  • "blockless-group" option for at-rule-empty-line-before. Use the "blockless-after-blockless" option instead.
  • "between-comments" option for comment-empty-line-before. Use the "after-comment" option instead.
  • "at-rules-without-declaration-blocks" option for max-nesting-depth. Use the "blockless-at-rules" option instead.
• Added: time-min-milliseconds rule, to replace time-no-imperceptible (#2289).
• Added: except: ["after-same-name"] option to at-rule-empty-line-before (#2225).
• Fixed: configOverrides now work with extends (#2295).
• Fixed: max-line-length no longer reports incorrect column positions for lines with url() or import (#2287).
• Fixed: selector-pseudo-class-no-unknown no longer warns for proprietary webkit pseudo-classes (#2264).
• Fixed: unit-no-unknown accepts fr units (#2308).