to-14.md

Migrating to 14.0.0

This release contains breaking changes. We know these can be disruptive, but they were needed to keep our dependencies up to date and stylelint free of security issues.

Users

There are five changes that may affect you:

• the syntax option and automatic inferral of syntax was removed
• Node.js 10 support was dropped
• the rules deprecated in 13.7.0 were removed
• the configOverrides option was removed
• the function-calc-no-invalid rule was removed

syntax option and automatic inferral of syntax

stylelint no longer includes syntaxes that:

• parse CSS-like syntaxes like SCSS, Sass, Less and SugarSS
• extract embedded styles from HTML, Markdown and CSS-in-JS object & template literals

If you use stylelint to lint anything other than CSS files, you will need to install and configure these syntaxes yourself. You can use the customSyntax option to do this, which is now available in the configuration object.

For example, to lint SCSS.

First, install the postcss-scss syntax as a dependency:

npm install --save-dev postcss-scss

Then, update your configuration object to use it:

{
  "customSyntax": "postcss-scss",
  "rules": {
    ..
  }
}

For other languages and embedded styles, we suggest the following PostCSS syntaxes:

• Less language (.less) use postcss-less
• Sass language (.sass) use postcss-sass
• SugarSS language (.sss) use sugarss
• CSS-in-JS embeds (.js, .jsx, .ts etc.) use @stylelint/postcss-css-in-js
• HTML, XML and HTML-like embeds (.html, .xml, .svelte, .vue etc.) use postcss-html
• Markdown embeds (.md, .markdown etc.) use postcss-markdown

(The postcss-html and postcss-markdown packages need a maintainer. The @stylelint/postcss-css-in-js package has issues. It will likely to be deprecated in the future in favour of smaller syntaxes that focus on only one library).

If you lint more than one styling language, then you can use the new overrides property. For example, to lint both CSS and SugarSS you can update your configuration object to include:

{
  "extends": ["stylelint-config-standard"],
  "overrides": [
    {
      "files": ["**/*.sss"],
      "customSyntax": "sugarss",
      "rules": {
        "block-closing-brace-empty-line-before": null,
        "block-closing-brace-newline-after": null,
        "block-closing-brace-newline-before": null,
        "block-closing-brace-space-before": null,
        "block-opening-brace-newline-after": null,
        "block-opening-brace-space-after": null,
        "block-opening-brace-space-before": null,
        "declaration-block-semicolon-newline-after": null,
        "declaration-block-semicolon-space-after": null,
        "declaration-block-semicolon-space-before": null,
        "declaration-block-trailing-semicolon": null
      }
    }
  ]
}

Which will extend the offical standard config, then use the overrides property to set the customSyntax property and turn off the rules that check braces and semicolons for SugarSS files.

You can then use stylelint to lint both CSS and SugarSS files:

npx stylelint "**/*.{css,sss}"

Node.js 10

Support for Node.js 10 was dropped. You should use the following or higher versions of Node.js:

• 12.20.0
• 14.13.1
• 16.0.0

Rules deprecated in 13.7.0

The rules deprecated in 13.7.0 were removed. You should refer to the list of alternatives in the 13.7.0 CHANGELOG entry and use them instead.

configOverrides option

The configOverrides option has been removed. Use the overrides property in the configuration object instead.

function-calc-no-invalid rule

The function-calc-no-invalid has be removed. You should remove it from your configuration object.

Plugin authors

There are two changes that may affect you:

• version 8 of PostCSS is now used in stylelint
• a disableFix secondary option was added

PostCSS 8

The behaviour of the parser has changed in PostCSS version 8. The following is now parsed as a Declaration when it was previously parsed as a Rule:

foo: {
  bar: baz;
}

If your plugin targets this construct, you'll need to update your logic.

Even though version 8 of PostCSS is used in stylelint, you can't use the new Visitor API as stylelint plugins are converted to use Once by stylelint itself. You should continue to use the walk* API.

disableFix secondary option

We previously suggested plugin authors provide this option. It is now available in stylelint itself, and you should remove the option from your plugin.