Skip to main content

Stylelint - CSS linter

https://stylelint.io/

A mighty CSS linter that helps you avoid errors and enforce conventions.

Vortex comes with a pre-configured Stylelint ruleset for Drupal projects.

info

Stylelint in Vortex is configured to lint custom modules only (web/modules/custom). The custom theme maintains its own Stylelint configuration within the theme directory.

Usage​

Check for violations​

# Lint all front-end code: Twig, JavaScript and CSS.
ahoy lint-fe
# Lint only CSS in custom modules.
ahoy cli "npm run lint-css"

Fix violations​

Stylelint fixes many violations automatically using the --fix flag.

# Fix all front-end lint issues.
ahoy lint-fe-fix
# Fix only CSS issues in custom modules.
ahoy cli "npm run lint-fix-css"

ahoy lint-fe and ahoy lint-fe-fix also run the lint and lint-fix scripts of the custom theme, which lint the theme's JavaScript and SCSS together. To lint only the theme's stylesheets, run the theme's own lint-css and lint-css-fix scripts:

ahoy cli "npm run --prefix=web/themes/custom/your_site_theme lint-css"
ahoy cli "npm run --prefix=web/themes/custom/your_site_theme lint-css-fix"

Configuration​

See configuration reference.

All global configuration takes place in the .stylelintrc.js file.

By default, Stylelint extends the following configuration and plugin:

  • stylelint-config-standard - the standard shareable configuration
  • stylelint-order - plugin that provides the order/* rules

The following rules are set on top of the standard configuration:

  • order/properties-alphabetical-order - declarations within a block must be in alphabetical order
  • at-rule-no-unknown - unknown at-rules are reported, except the Sass at-rules @extend, @at-root, @debug, @warn, @error, @if, @else, @for, @each, @while, @include, @mixin, @function, @return and @content
  • selector-class-pattern, selector-id-pattern, custom-property-pattern and keyframes-name-pattern - disabled, so class, ID, custom property and keyframes names are not forced into a naming pattern
  • no-descending-specificity - disabled
  • font-family-no-missing-generic-family-keyword - disabled

Targets include custom modules only. The --allow-empty-input flag makes the run exit without an error when the glob matches no files:

{
  "scripts": {
    "lint-css": "stylelint --allow-empty-input \"web/modules/custom/**/*.css\"",
    "lint-fix-css": "stylelint --allow-empty-input \"web/modules/custom/**/*.css\" --fix"
  }
}

Adding or removing targets in package.json:

{
  "scripts": {
    "lint-css": "stylelint --allow-empty-input \"web/modules/custom/**/*.css\" \"web/sites/default/**/*.css\""
  }
}

The stylelint, stylelint-config-standard and stylelint-order packages are declared in the devDependencies of the root package.json and installed by ahoy fei.

Theme configuration​

The custom theme ships its own .stylelintrc.json and its own package.json, because a theme carries its own front-end tooling and can be moved into a separate repository.

The theme configuration extends stylelint-config-standard and stylelint-config-standard-scss, loads the stylelint-scss plugin, uses the string formatter and sets the following rules:

  • scss/at-extend-no-missing-placeholder - @extend must target a placeholder selector
  • scss/comment-no-empty - disabled
  • scss/dollar-variable-pattern - $variable names must match ^_?[a-z]+([a-z0-9-]+[a-z0-9]+)?$

The theme's lint-css script targets scss/**/*.scss, and the configuration ignores scss/_components.scss, fonts/**/*.scss and build/.* through the ignoreFiles key.

Ignoring​

Ignoring paths globally takes place in the ignoreFiles key of the configuration file, as the theme configuration does:

{
  "ignoreFiles": [
    "scss/_components.scss",
    "fonts/**/*.scss",
    "build/.*"
  ]
}

To ignore all Stylelint rules within a file, place in the file header:

/* stylelint-disable */

To ignore a specific rule within a file, place in the file header:

/* stylelint-disable selector-max-id, declaration-no-important */

To ignore rules for a code block:

/* stylelint-disable declaration-no-important */
a {
  color: red !important;
}
/* stylelint-enable declaration-no-important */

To ignore only the next line:

a {
  /* stylelint-disable-next-line declaration-no-important */
  color: red !important;
}

To ignore rules for the current line (inline):

a {
  color: red !important; /* stylelint-disable-line declaration-no-important */
}

Continuous integration​

Stylelint runs in the lint job of the continuous integration pipeline and fails the build on violations. The custom modules and the custom theme are linted in separate steps; the theme step is skipped when VORTEX_FRONTEND_BUILD_SKIP is set to 1.

Ignoring failures​

Set the VORTEX_CI_NODEJS_LINT_IGNORE_FAILURE environment variable to 1. The variable is shared with ESLint, which runs in the same step. The tool still runs and reports violations.

➡️ See Continuous integration > Ignore tool failures