Shareable Stylelint Config

This npm package provides a set of shareable configurations for Stylelint 15+ — a linter for CSS and SCSS.

📄 About

Collection of stylelint configurations that can be used to enforce consistent styling across CSS and SCSS files.

The configurations provided in this package are designed to be flexible and easily extendable, allowing developers to customize the rules to fit their specific needs.

→ Purpose

Provide a set of opinionated yet flexible configurations for stylelint that help developers to maintain consistent code styling and avoid common errors. The configurations provided in this package:

• Provide a solid foundation for a project's code styling that can be extended and modified as needed
• Enforce common best practices for CSS and SCSS development, such as using consistent indentation, avoiding vendor prefixes, and avoiding unnecessary specificity
• Catch common errors, such as missing units for numeric values, using invalid colors, and using unsupported or deprecated CSS features
• Help developers to maintain consistency across their codebase by providing clear and consistent rules for code styling.

💿 Installation

To use @staxomni/stylelint-config in an app that uses CSS or SCSS, you need to install stylelint and @staxomni/stylelint-config in the app's directory within the monorepository.

For example, if you have a Next.js app located in apps/web, you would install stylelint and @staxomni/stylelint-config in the apps/web directory using the following command:

pnpm --filter=web add -D stylelint @staxomni/stylelint-config

💻 Usage

You can use one of the provided configurations by adding it to your stylelint configuration file.

For example, to use the @staxomni/stylelint-config/scss configuration for your Next.js app, add the following to your apps/web/.stylelintrc.js file:

→ CSS

module.exports = {
  extends: '@staxomni/stylelint-config/css',
}

→ SCSS

module.exports = {
  extends: '@staxomni/stylelint-config/scss',
}

You can also customize the rules provided in the configurations or create your own configuration that extends one of the provided configurations. For more information on how to configure stylelint, see the stylelint configuration documentation.

→ Extending

You can extend one of the provided configurations in @staxomni/stylelint-config by adding an overrides section to your stylelint configuration file. For example, to use a mixed CSS/SCSS configuration that ignores files in the dist directory, add the following to your apps/web/.stylelintrc.js file:

module.exports = {
  ignoreFiles: ['dist/**'],
  extends: '@staxomni/stylelint-config/scss',
  overrides: [
    {
      files: ['**/*.css'],
      extends: '@staxomni/stylelint-config/css',
    },
  ],
}

This configuration will extend the @staxomni/stylelint-config/scss configuration for SCSS files and the @staxomni/stylelint-config/css configuration for CSS files, and will ignore all files in the dist directory.

→ Add a NPM Script

To add an NPM script for running stylelint use command, which will add the lint:styles script to the scripts section of your package.json.

# pnpm pkg set scripts.lint:styles="stylelint --fix **/*.{css,scss}"

This will run stylelint on all CSS and SCSS files in your app's directory and its subdirectories. You can customize the files and directories to be linted as needed.

🚗 Under The Hood

Under the hood, these configurations include various plugins and extends to enforce a range of best practices and standards for CSS and SCSS development.

css.js

• Plugins
  • stylelint-order
  • stylelint-no-unsupported-browser-features
  • stylelint-high-performance-animation
• Extends
  • stylelint-config-standard
  • stylelint-a11y

scss.js

• Plugins
  • stylelint-order
  • stylelint-no-unsupported-browser-features
  • stylelint-high-performance-animation
• Extends
  • stylelint-config-standard-scss
  • stylelint-config-sass-guidelines
  • stylelint-a11y