Skip to main content

@roots/bud-stylelint

Adds Stylelint support to your project.

Installation​

npm install @roots/bud-stylelint --save-dev

Usage​

The bud.stylelint class provides an API for integrating Stylelint, a modern linter that helps you avoid errors and enforce conventions in your styles. It has a variety of methods and properties that allow for detailed configuration of how Stylelint should behave.

Options​

The bud.stylelint API provides a number of options that can be used to configure Stylelint. These options include:

  • cache: Enables caching of lint results to improve performance on subsequent runs. By default, it's set to true unless in a continuous integration (CI) environment.
  • cacheLocation: Specifies the location of the cache. By default, it's set to a directory named stylelint in the cache directory.
  • config: Specifies the Stylelint configuration object. By default, it finds the first file with stylelint in its name and uses that as the config.
  • context: The context path. By default, it's set to the @src directory.
  • failOnError: Indicates whether to fail the build when errors are detected. By default, this is true in production environments.
  • failOnWarning: Indicates whether to fail the build when warnings are detected. By default, this is set to false.
  • files: Specifies the files to be linted. By default, this is undefined, meaning that all files will be linted.
  • fix: Indicates whether Stylelint should try to fix any issues it finds. By default, this is set to false.
  • stylelintPath: The path to the Stylelint binary. By default, this is undefined, meaning that the binary in the node_modules directory will be used.

Methods​

The bud.stylelint API provides several methods for interacting with these options. These methods include:

  • extends(config): Allows you to extend a base Stylelint configuration.
  • setRules(rules): Sets the Stylelint rules to be used.
  • getRules(): Gets the currently set Stylelint rules.
  • setPlugins(plugins): Sets the Stylelint plugins to be used.
  • getPlugins(): Gets the currently set Stylelint plugins.
  • setFailOnError(boolean): Sets whether the build should fail when Stylelint detects errors.
  • setFailOnWarning(boolean): Sets whether the build should fail when Stylelint detects warnings.
  • setFiles(files): Sets the files to be linted.
  • getFiles(): Gets the files to be linted.

Example bud.js config​

Here's an example of how you can use the bud.stylelint API in your Bud configuration:

import {type Bud} from '@roots/bud'

export default async (bud: Bud) => {
  bud.entry('app', ['app.js', 'app.css'])

  bud.stylelint
    .extends([`@roots/bud-stylelint/config`])
    .setRules({'no-descending-specificity': null})
    .setFailOnError(bud.isProduction)
    .setFailOnWarning(false)
    .setFix(true)
}

In this example, we are extending the default @roots/bud-stylelint/config, setting a custom rule no-descending-specificity, and adjusting the behavior for errors and warnings based on the environment. We also set setFix(true) to instruct Stylelint to attempt to fix any issues it detects.

Using a stylelint config​

You can also configure stylelint using a stylelint config file.

bud.js allows for you to write your stylelint config in CommonJS, ESM, TypeScript, JSON or YML. This file should be placed in the root of your project or the project ./config directory.

export default {
  extends: [`@roots/bud-stylelint/config`],
  rules: {'no-descending-specificity': null},
}