Stylelint

Overview

Stylelint is a robust, open-source linter designed specifically for CSS and CSS-like syntaxes, including SCSS, Less, and SugarSS. Developed in 2015, its primary purpose is to help developers and teams maintain consistent coding styles and prevent errors within their stylesheets. By defining a set of rules, Stylelint can automatically check CSS code against a project's established conventions, flagging issues such as incorrect property ordering, invalid values, or inconsistent indentation. This automated enforcement helps streamline code reviews and ensures that all contributors adhere to the same quality standards, regardless of individual preferences.

The tool is particularly valuable for projects with multiple developers, large codebases, or those requiring strict adherence to style guides. Its high configurability allows teams to tailor rules to their exact needs, from enforcing BEM methodology to ensuring accessibility best practices. Stylelint operates by parsing CSS code into an abstract syntax tree (AST) and then applying a series of rules to this tree. Each rule checks for a specific pattern or condition, reporting violations with clear messages that often include suggestions for correction. This detailed feedback loop aids developers in quickly understanding and resolving issues.

Stylelint integrates seamlessly into various development workflows. It can be run as a command-line tool, integrated into build processes using task runners like npm scripts or webpack, or embedded directly into IDEs for real-time feedback. Its ecosystem includes numerous plugins and shareable configurations, allowing developers to extend its capabilities or adopt popular style guides such as stylelint-config-standard. While tools like ESLint focus on JavaScript code quality, or Prettier on opinionated code formatting across languages, Stylelint provides a dedicated solution for the intricacies of CSS, addressing a distinct need in the front-end development stack.

The project's open-source nature means it benefits from community contributions, ensuring its continued evolution and adaptation to new CSS features and best practices. Its developer experience is noted for clear error reporting and straightforward integration, making it an effective choice for maintaining styling consistency and preventing common CSS errors across projects.

Key features

• Extensive Rule Set: Offers over 170 built-in rules for catching errors, enforcing conventions, and preventing stylistic inconsistencies in CSS, SCSS, and Less Stylelint User Guide on rules.
• High Configurability: Allows users to enable, disable, or customize individual rules, set severity levels, and define custom messages, supporting highly specific project requirements.
• Processor Support: Capable of linting various CSS preprocessor syntaxes, including SCSS, Less, and SugarSS, ensuring consistent styling across different stylesheet languages.
• Plugin System: Supports a rich plugin ecosystem that extends its functionality with custom rules, formatters, and processors for unique use cases or emerging CSS features.
• Shareable Configurations: Enables teams to define and share their Stylelint configurations across multiple projects, promoting consistency and reducing setup time.
• Autofixing: Many rules support an autofix option, allowing Stylelint to automatically correct certain stylistic issues, reducing manual refactoring effort.
• IDE Integration: Integrates with popular Integrated Development Environments (IDEs) like VS Code and WebStorm, providing real-time feedback and linting results directly within the editor.
• CLI and API: Provides both a Command Line Interface (CLI) for easy execution in build scripts and a JavaScript API for programmatic integration into larger systems.
• CSS Modules and JSS Support: Offers specific configurations and plugins to handle CSS Modules and JavaScript-in-CSS (JSS) patterns, adapting to modern styling approaches.
• Clear Error Reporting: Generates detailed and understandable error messages, often with line numbers and suggested fixes, to help developers quickly resolve issues.

Pricing

Stylelint is an open-source project distributed under the MIT License, making it free to use for all purposes, including commercial applications. There are no licensing fees, subscription costs, or premium tiers associated with its core functionality or official plugins.

Additional costs may arise from integrating Stylelint into commercial CI/CD pipelines or development environments that themselves incur costs. However, Stylelint itself does not impose any direct financial burden Stylelint User Guide.

Common integrations

• ESLint: Often used alongside ESLint through tools like eslint-plugin-stylelint or shared configuration files to manage both JavaScript and CSS linting consistently. ESLint is a common linter for JavaScript codebases ESLint Getting Started Guide.
• Prettier: Integrates with Prettier for opinionated code formatting, often with Stylelint handling stylistic rules that Prettier doesn't cover, or vice-versa, using tools like stylelint-config-prettier Prettier Lint Integration documentation.
• Webpack: Can be integrated into Webpack build processes using stylelint-webpack-plugin to lint CSS files during compilation and prevent deployment of faulty styles.
• Gulp/Grunt: Works with Gulp and Grunt task runners via dedicated plugins (e.g., gulp-stylelint) to automate linting tasks as part of a front-end build pipeline.
• VS Code: Supported by the official Stylelint extension for Visual Studio Code, providing real-time linting feedback directly within the editor.
• Git Hooks: Utilized with tools like Husky or lint-staged to run Stylelint checks automatically on staged Git files before commits, ensuring that only lint-clean code enters the repository.
• CI/CD Pipelines: Easily integrated into continuous integration/continuous delivery workflows (e.g., GitHub Actions, GitLab CI, Jenkins) to enforce code quality checks on every push or pull request.
• PostCSS: Functions as a PostCSS plugin via postcss-stylelint, allowing it to lint CSS after other PostCSS transformations have been applied.
• Create React App / Next.js: Can be configured in projects scaffolded with Create React App or Next.js to provide CSS linting within those environments, often requiring custom configurations or overrides.

Alternatives

• ESLint: A widely used linter primarily for JavaScript, often extended with plugins to handle other file types. While not dedicated to CSS, it can be configured for some styling checks, particularly within JavaScript files using CSS-in-JS.
• Prettier: An opinionated code formatter that enforces a consistent style by reprinting code. Unlike Stylelint, Prettier focuses solely on formatting rather than identifying potential errors or enforcing complex architectural rules.
• Biome: A web toolchain that combines a formatter, linter, and bundler in one. Biome aims for a unified developer experience, providing linting capabilities that cover JavaScript, TypeScript, and JSX, with ongoing development for CSS support.

Getting started

To begin using Stylelint, you typically install it as a development dependency in your project and then create a configuration file. This example demonstrates a basic setup for linting CSS files.

# 1. Initialize a new Node.js project (if you haven't already)
npm init -y

# 2. Install Stylelint and a standard configuration
npm install stylelint stylelint-config-standard --save-dev

Next, create a .stylelintrc.json file in your project root to configure Stylelint. This example extends the recommended standard configuration:

// .stylelintrc.json
{
  "extends": "stylelint-config-standard",
  "rules": {
    // Override or add custom rules here
    "indentation": 2,
    "color-no-invalid-hex": true,
    "declaration-block-single-line-max-declarations": 1
  }
}

Now, create a sample CSS file, styles.css:

/* styles.css */
.container {
  color: #ff;
  display: flex;
  padding-left: 10px;
}

.item {
  width: 100px;
  height: 50px; /* missing semicolon */
  background-color: blue;
}

Finally, you can run Stylelint from your terminal to check the styles.css file:

# Run Stylelint on your CSS files
npx stylelint "**/*.css"

This command will output any violations of the configured rules, such as the invalid hex color or missing semicolon in the example above. For more detailed usage and advanced configurations, refer to the Stylelint User Guide.