rickhanlonii / stylelint

A mighty, modern CSS linter

stylelint

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

Features

• Over one hundred and sixty built-in rules. Geared towards standard CSS syntax, these can:
  • Catch possible errors: e.g., invalid standard CSS syntax, duplicates, and overrides.
  • Limit language features: e.g.:
    • Disallow specific units, properties, functions, and at-rules.
    • Limit the specificity and quantity of selectors.
    • Enforce patterns for selectors and custom properties.
  • Enforce stylistic conventions: e.g., whitespace, case, notation, and quotes.
• Understands the latest CSS syntax: Including custom properties, calc() and level 4 selectors.
• 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, or make use of plugins written by the community.
• Automatically fixes some stylistic violations: Save time by having stylelint fix your code with this experimental feature.
• Shareable configs: If you don't want to craft your own config, you can extend a shareable config. Or you can craft your own config and share with your team and/or the community.
• Works with embedded styles: Within <style> tags (used by Vue and Web Components) and Markdown code fences.
• Parses CSS-like syntaxes: The linter is powered by PostCSS, so it can be configured and extended to understand any syntax that PostCSS can parse, including SCSS, SugarSS, and Less.
• Options validator: So that you can be confident that your config is valid.
• Well tested: Over ten 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 text editor (atom, vscode etc)
   • via a plugin for your build tool (webpack, gulp 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 suggest using either stylelint-config-standard or stylelint-config-recommended. We update the configs with each new release of stylelint, so it's easy to stay up to date. Both configs are geared towards standard CSS syntax. If you use non-standard syntax (like @if etc.) then you might want to use a community config designed for that syntax e.g. stylelint-config-recommended-scss. The recommended config turns on just the possible error rules. The standard config builds on top of the recommended config by additionally turning on over 60 of stylelint's stylistic rules with sensible defaults. You can always override specific rules after extending either config. When using either config, you'll likely want to add (and configure to your specific needs) some of the rules that limit language features. Alternately, you can search for another 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.

Interested in the project vision? Please read our VISION document.

Semantic Versioning Policy

stylelint follows semantic versioning. However, due to the nature of stylelint as a code quality tool, it's not always clear when a minor or major version bump occurs. To help clarify this for everyone, based on ESLint's semantic versioning policy we've defined the following semantic versioning policy for stylelint:

• Patch release (intended to not break your lint build)

  • A bug fix in a rule that results in stylelint reporting fewer errors.
  • A bug fix to the CLI or core (including formatters).
  • Improvements to documentation.
  • Non-user-facing changes such as refactoring code, adding, deleting, or modifying tests, and increasing test coverage.
  • Re-releasing after a failed release (i.e., publishing a release that doesn't work for anyone).

• Minor release (might break your lint build)

  • A bug fix in a rule that results in stylelint reporting more errors.
  • A new rule is created.
  • A new option to an existing rule that does not result in stylelint reporting more errors by default.
  • An existing rule is deprecated.
  • A new CLI capability is created.
  • New capabilities to the public API are added (new classes, new methods, new arguments to existing methods, etc.).
  • A new formatter is created.

• Major release (likely to break your lint build)

  • A change in the documented behaviour of an existing rule results in stylelint reporting more errors by default.
  • An existing rule is removed.
  • An existing formatter is removed.
  • Part of the public API is removed or changed in an incompatible way.

According to our policy, any minor update may report more errors than the previous release (ex: from a bug fix). As such, we recommend using the tilde (~) in package.json e.g. "stylelint": "~7.2.0" to guarantee the results of your builds.

License