Guide · Open source
How to use Stylelint: install, configure and lint CSS
Updated · written with AI from the project's own documentation and checked against our catalogue data
Stylelint is a free, open-source linter for CSS and CSS-like code. It catches mistakes such as malformed grid areas, misspelled property names and duplicate selectors, and it enforces style conventions your team picks. This guide explains what it checks, how it is set up and how to use it alongside other tools, so you can decide whether it fits your project.
Stylelintstylelint/stylelint · ★ 11.5k · MIT Install options & downloads Quick start
- 1Check prerequisites. Make sure Node.js is available, since Stylelint is a JavaScript package.
- 2Read the getting started guide. Open docs/user-guide/get-started.md in the project repository for setup steps.
- 3Choose your rules. Browse the rules list and select the checks that match your team's conventions.
- 4Write a shared configuration. Put your settings in a configuration file or shareable config so everyone uses the same rules.
- 5Run the linter on your CSS. Lint your stylesheets and review the reported errors and warnings.
- 6Apply automatic fixes. Use automatic fixing for problems that support it, then fix the rest by hand.
- 7Add a formatter. Run Prettier alongside Stylelint so formatting and linting work together.
What Stylelint checks in your CSS
Stylelint looks for two kinds of problems. The first are errors: invalid things like malformed grid areas, valid but problematic things like duplicate selectors, and unknown things like misspelled property names.
The second are conventions your team chooses, such as disallowing specific units, enforcing naming patterns for custom properties, setting limits on the number of ID selectors, or specifying notations for modern color functions.
- Avoid errors: invalid, problematic and unknown code
- Enforce conventions: disallowed units, naming patterns, selector limits, color notation
Install Stylelint with a package manager
Stylelint is distributed as a JavaScript package, so you need Node.js in your project. The project's README lists Node.js as the prerequisite. The README's install instruction shown in the source is to clone the repository, which is useful if you want to work on Stylelint itself rather than just use it.
For most projects, installing the npm package is the route to take. Check the Getting started guide in the project's docs for the exact package-manager steps for your setup.
git clone https://github.com/stylelint/stylelintConfigure the rules you want
Stylelint ships with over 150 built-in rules for modern CSS syntax and features. You turn on the rules that match your conventions. The project documents configuration in its Configuring and Rules guides.
You can also share settings across projects using shareable configs, which you can create or extend. Options for each rule are described in the Options guide.
- Rules: docs/user-guide/rules.md
- Configuring: docs/user-guide/configure.md
- Shareable configs: supported, can be created or extended
Lint SCSS, Sass and Less, and embedded styles
Stylelint can parse CSS-like languages including SCSS, Sass, Less and SugarSS. It can also extract embedded styles from HTML, Markdown and CSS-in-JS template literals.
If you write a preprocessor syntax, check that your setup includes the parser for that language before relying on results.
- CSS-like syntaxes: SCSS, Sass, Less, SugarSS
- Embedded styles: HTML, Markdown, CSS-in-JS template literals
Fix problems automatically and ignore code when needed
Stylelint can automatically fix some problems where a fix is possible. Problems without an automatic fix still need to be changed by hand.
When a rule is wrong for a specific case, you can ignore that code. The Ignoring code guide covers how. Use the CLI guide for command-line options and the Node.js API guide if you want to run Stylelint from your own scripts.
- Automatic fixing applies only where a fix exists
- Ignoring code: docs/user-guide/ignore-code.md
- CLI: docs/user-guide/cli.md
- Node.js API: docs/user-guide/node-api.md
Use Stylelint with Prettier and extend it with plugins
The README recommends using a pretty printer like Prettier alongside Stylelint. Linters and pretty printers are complementary: the linter flags errors and conventions, while the printer handles formatting.
Stylelint supports plugins so you can write custom rules. The Writing plugins guide explains how.
- Pair with Prettier for formatting
- Custom rules: docs/developer-guide/plugins.md
What people use it for
- Catching misspelled property names and malformed grid areas before a release
- Keeping naming patterns for custom properties consistent across a team
- Linting SCSS or Less files in a shared front-end codebase
- Enforcing limits such as the number of ID selectors in a project
- Pairing linting with Prettier for consistent CSS in a team workflow
Frequently asked questions
Is Stylelint free to use?
Yes. Stylelint is released under the MIT License, which is a permissive open-source licence. The full licence text is linked from the project's License section.
Does Stylelint require Node.js?
Yes. The project is distributed as a JavaScript package and its listed prerequisite is Node.js. If you only need a few static CSS rules and do not want a Node.js toolchain, a different tool may suit you better.
Can Stylelint lint SCSS, Sass and Less?
Yes. Stylelint can parse SCSS, Sass, Less and SugarSS. It can also extract embedded styles from HTML, Markdown and CSS-in-JS template literals.
Can Stylelint fix my CSS automatically?
Stylelint can automatically fix some problems where a fix is possible. Other problems need to be corrected manually.
Does Stylelint replace Prettier?
No. The README recommends using Prettier alongside Stylelint because linters and pretty printers are complementary. Stylelint checks for errors and conventions, while Prettier handles formatting.
What are the alternatives to Stylelint?
The source lists Prettier, CSSLint and sass-lint as comparable projects. Prettier is a formatter that is often used alongside Stylelint rather than instead of it.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Stylelint suits front-end teams that want consistent CSS, developers who want to catch typos and invalid CSS early, and projects using SCSS, Sass or Less. It is less suitable if you only need a handful of static CSS rules without a Node.js toolchain, or if you want a visual editor or a preprocessor, since Stylelint only checks code.
Install options & downloads