Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Document 14.0.0 migration guide (#5563)
Co-authored-by: Masafumi Koba <473530+ybiquitous@users.noreply.github.com> Co-authored-by: Aleks Hudochenkov <aleks@hudochenkov.com>
- Loading branch information
1 parent
585d28a
commit bf5fe4e
Showing
23 changed files
with
571 additions
and
378 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,4 +1,4 @@ | ||
# Writing formatters | ||
# Writing custom formatters | ||
|
||
A formatter is a function with the following signature: | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,35 +1,29 @@ | ||
# Working on syntaxes | ||
# Writing custom syntaxes | ||
|
||
Please help us enhance and debug the [syntaxes](../about/syntaxes.md) we use in stylelint: | ||
Custom syntaxes are [PostCSS syntaxes](https://github.com/postcss/postcss#syntaxes) written by the community to support other styling languages or CSS-in-JS libraries using the [`customSyntax` option](../user-guide/usage/options.md#customSyntax) | ||
|
||
- [postcss-css-in-js](https://github.com/stylelint/postcss-css-in-js) | ||
- [postcss-html](https://github.com/gucong3000/postcss-html) | ||
- [postcss-less](https://github.com/webschik/postcss-less) | ||
- [postcss-markdown](https://github.com/stylelint/postcss-markdown) | ||
- [postcss-sass](https://github.com/AleshaOleg/postcss-sass) | ||
- [postcss-scss](https://github.com/postcss/postcss-scss) | ||
|
||
To contribute to a syntax, you should: | ||
|
||
1. Familiarize yourself with PostCSS's [how to write custom syntax](https://github.com/postcss/postcss/blob/master/docs/syntax.md) guide. | ||
2. Use the [`syntax: *` labels](https://github.com/stylelint/stylelint/labels?utf8=%E2%9C%93&q=syntax%3A) to identify which syntax is behind an issue. | ||
3. Go to the repository for that syntax. | ||
4. Read their contributing guidelines. | ||
|
||
## Workarounds | ||
|
||
Fixing bugs in syntaxes can take time. stylelint can work around these bug by turning off autofix for incompatible sources. Autofix can then remain safe to use while contributors try to fix the underlying issue. | ||
To write one, familiarize yourself with PostCSS's [how to write custom syntax](https://github.com/postcss/postcss/blob/main/docs/syntax.md) guide. | ||
|
||
### Current workarounds | ||
Existing syntaxes that you can use for reference include: | ||
|
||
stylelint currently turns off autofix for sources that contain: | ||
|
||
- ~~nested tagged template literals ([issue #4119](https://github.com/stylelint/stylelint/issues/4119))~~ | ||
|
||
### Add a workaround | ||
|
||
To add a new workaround, you should: | ||
|
||
1. Add code to [`lib/lintSource.js`](https://github.com/stylelint/stylelint/blob/master/lib/lintSource.js) to detect the incompatible pattern. | ||
2. Add a corresponding test to [`lib/__tests__/standalone-fix.test.js`](https://github.com/stylelint/stylelint/blob/master/lib/__tests__/standalone-fix.test.js). | ||
3. Document the workaround in [`docs/developer-guides/syntaxes.md`](https://github.com/stylelint/stylelint/blob/master/docs/developer-guide/syntaxes.md). | ||
- [postcss-scss](https://github.com/postcss/postcss-scss) | ||
- [postcss-less](https://github.com/shellscape/postcss-less) | ||
|
||
We recommend creating a shared-config that: | ||
|
||
- extends the [standard config](https://github.com/stylelint/stylelint-config-standard) | ||
- bundles your custom syntax | ||
- turns off any incompatible built-in rules | ||
|
||
For example, if you're creating a syntax for a CSS-in-JS library called "foo" then we recommend creating a shared-config called "stylelint-config-standard-foo" with the following content: | ||
|
||
```json | ||
{ | ||
"extends": ["stylelint-config-standard"], | ||
"customSyntax": "postcss-foo", | ||
"rules": { | ||
"at-rule-no-unknown": null, | ||
.. | ||
} | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,132 @@ | ||
# 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](../user-guide/usage/options.md#customSyntax) to do this, which is now available in the configuration object. | ||
|
||
For example, to lint SCSS. | ||
|
||
First, install the [postcss-scss](https://www.npmjs.com/package/postcss-scss) syntax as a dependency: | ||
|
||
```shell | ||
npm install --save-dev postcss-scss | ||
``` | ||
|
||
Then, update your configuration object to use it: | ||
|
||
```json | ||
{ | ||
"customSyntax": "postcss-scss", | ||
"rules": { | ||
.. | ||
} | ||
} | ||
``` | ||
|
||
For other languages and embedded styles, we suggest the following [PostCSS syntaxes](https://github.com/postcss/postcss#syntaxes): | ||
|
||
- Less language (`.less`) use [postcss-less](https://www.npmjs.com/package/postcss-less) | ||
- Sass language (`.sass`) use [postcss-sass](https://www.npmjs.com/package/postcss-sass) | ||
- SugarSS language (`.sss`) use [sugarss](https://www.npmjs.com/package/sugarss) | ||
- CSS-in-JS embeds (`.js`, `.jsx`, `.ts` etc.) use [@stylelint/postcss-css-in-js](https://www.npmjs.com/package/@stylelint/postcss-css-in-js) | ||
- HTML, XML and HTML-like embeds (`.html`, `.xml`, `.svelte`, `.vue` etc.) use [postcss-html](https://www.npmjs.com/package/postcss-html) | ||
- Markdown embeds (`.md`, `.markdown` etc.) use [postcss-markdown](https://www.npmjs.com/package/postcss-markdown) | ||
|
||
(The [postcss-html](https://www.npmjs.com/package/postcss-html) and [postcss-markdown](https://www.npmjs.com/package/postcss-markdown) packages need a maintainer (see [this issue](https://github.com/stylelint/stylelint/issues/5583)). The [@stylelint/postcss-css-in-js](https://www.npmjs.com/package/@stylelint/postcss-css-in-js) package [has issues](https://github.com/stylelint/stylelint/issues/4574). It will likely to be deprecated in the future in favour of smaller syntaxes that focus on only one library (see [this issue](https://github.com/stylelint/postcss-css-in-js/issues/225))). | ||
|
||
If you lint more than one styling language, then you can use the new [`overrides` property](../user-guide/configure.md#overrides). For example, to lint both CSS and [SugarSS](https://github.com/postcss/sugarss) you can update your configuration object to include: | ||
|
||
```json | ||
{ | ||
"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](https://github.com/stylelint/stylelint-config-standard), 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: | ||
|
||
```shell | ||
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](../../CHANGELOG.md#1370) and use them instead. | ||
|
||
### `configOverrides` option | ||
|
||
The `configOverrides` option has been removed. Use the [`overrides` property](../user-guide/configure.md#overrides) 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](../user-guide/configure.md#disableFix) 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`: | ||
|
||
```css | ||
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](https://github.com/postcss/postcss/releases/tag/8.0.0) 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. |
Oops, something went wrong.