Stylelint — Modern CSS Linter with 170+ Rules

Introduction

Stylelint is a CSS linter built on PostCSS that catches errors and enforces style conventions across stylesheets. It supports modern CSS features, preprocessor syntaxes like SCSS and Less, and CSS-in-JS libraries, making it the standard tool for maintaining stylesheet quality in frontend projects.

What Stylelint Does

• Parses and lints CSS, SCSS, Sass, Less, and SugarSS files for syntax errors and convention violations
• Offers 170+ built-in rules covering properties, selectors, values, and formatting
• Auto-fixes many issues such as shorthand property ordering and whitespace inconsistencies
• Integrates with editors (VS Code, WebStorm) for real-time feedback while coding
• Supports CSS-in-JS through community syntaxes for styled-components, Emotion, and others

Architecture Overview

Stylelint is a Node.js tool that uses PostCSS to parse stylesheets into an AST. Each enabled rule is a function that walks the AST and reports violations. Rules are loaded from the base configuration and any extended shared configs. A plugin system allows community rules that follow the same AST-walking pattern. The --fix flag applies auto-fixable changes by modifying the AST and serializing it back to source.

Self-Hosting & Configuration

• Install as a devDependency alongside a shared config like stylelint-config-standard
• Configuration lives in .stylelintrc.json, .stylelintrc.yml, or the stylelint key in package.json
• Extend shared configs and override individual rules in the rules object
• Add plugins (e.g., stylelint-order, stylelint-scss) for additional rule sets
• Integrate into CI with npx stylelint "src/**/*.css" as a build step

Key Features

• Comprehensive rule set covering modern CSS syntax including custom properties and nesting
• Shared configs enable one-line setup for standard, recommended, or framework-specific conventions
• Plugin ecosystem for SCSS-specific rules, property ordering, and BEM naming validation
• Auto-fix mode corrects whitespace, shorthand, and other fixable violations in place
• Editor integrations provide inline diagnostics and quick-fix actions

Comparison with Similar Tools

• ESLint — lints JavaScript/TypeScript, not CSS; projects typically use both side by side
• Prettier — formats code but does not catch logical CSS errors or enforce naming conventions
• css-lint (CSSLint) — older CSS linter with fewer rules and no plugin system
• PostCSS plugins — transform CSS but do not provide lint-and-report workflow
• Biome — fast linter/formatter for JS/TS with emerging CSS support, but not yet feature-complete for stylesheets

FAQ

Q: Can Stylelint lint Tailwind CSS utility classes? A: Tailwind utility classes are in HTML/JSX, not CSS files. Stylelint focuses on stylesheet files, but plugins exist to ignore Tailwind-specific at-rules like @apply and @tailwind.

Q: How do I disable a rule for a specific line? A: Use /* stylelint-disable-next-line rule-name */ comments, similar to ESLint disable comments.

Q: Does Stylelint replace Prettier for CSS? A: They serve different purposes. Prettier handles formatting; Stylelint catches errors and enforces conventions. Many teams run both.

Q: Can I write custom rules? A: Yes. Custom rules are PostCSS plugins that follow Stylelint's rule API. Publish them as npm packages or include them locally.

Sources

• https://github.com/stylelint/stylelint
• https://stylelint.io/