Skip to content

Commit

Permalink
feat!: Upgrade to Stylelint 14 馃帀
Browse files Browse the repository at this point in the history 
Closes #233

- Stylelint dependency changed to point to v14 branch on GitHub (Will
  need to be changed to the packaged version once Stylelint 14 is
  published to npm.)
- Default values for `validate` and `snippet` options set to
  `['css', 'postcss']`
- Removed `syntax` option
- Removed `configOverrides` option
- Documented changes and provided migration path in readme
- Made appropriate changes in tests
- Removed tests for removed features
  • Loading branch information
@adalinesimonian
adalinesimonian committed Oct 8, 2021
1 parent 82a8a90 commit 574a993
Show file tree
Hide file tree
Showing 19 changed files with 475 additions and 927 deletions.
179 changes: 98 additions & 81 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ The official [Visual Studio Code](https://code.visualstudio.com/) extension to l

![screenshot](media/screenshot.png)

> **Notice:** 1.x of this extension has breaking changes from 0.x versions, including, but not limited to, changes to which documents are linted by default. See the [migration section](#Migrating-from-vscode-stylelint-0.x/Stylelint-13.x) for more information.
The extension first looks for a copy of stylelint installed in the open workspace folder, then for a globally installed version if it can't find one.

## Installation
Expand All @@ -16,95 +18,110 @@ The extension first looks for a copy of stylelint installed in the open workspac

Read the [extension installation guide](https://code.visualstudio.com/docs/editor/extension-gallery) for more details.

### Recommended setup (optional)

<img align="right" width="430" alt="duplicate messages from both the built-in linter and vscode-stylelint" src="https://raw.githubusercontent.com/stylelint/vscode-stylelint/main/media/duplicate.png">
### Recommended Setup (optional)

To prevent both [VS Code's built-in linters](https://code.visualstudio.com/docs/languages/css#_syntax-verification-linting) `[css]` `[less]` `[scss]` and this extension `[stylelint]` from reporting the same errors as seen in the screenshot, disable the built-in linters in either the [user or workspace settings](https://code.visualstudio.com/docs/getstarted/settings):
To prevent both [VS Code's built-in linters](https://code.visualstudio.com/docs/languages/css#_syntax-verification-linting) `[css]` `[less]` `[scss]` and this extension `[stylelint]` from reporting the same errors, disable the built-in linters in either the [user or workspace settings](https://code.visualstudio.com/docs/getstarted/settings):

```json
"css.validate": false,
"less.validate": false,
"scss.validate": false
```

<img width="430" alt="Screenshot of duplicate error messages" src="https://raw.githubusercontent.com/stylelint/vscode-stylelint/main/media/duplicate.png">

_An example of duplicate error messages from both the built-in linter and vscode-stylelint._

## Usage

Once a user follows [the stylelint startup guide](https://stylelint.io/user-guide/get-started) by creating a [configuration](https://stylelint.io/user-guide/configuration) file or by editing [`stylelint.*` VSCode settings](#extension-settings), stylelint automatically validates documents with these [language identifiers](https://code.visualstudio.com/docs/languages/overview#_language-id):

<img align="right" width="430" alt="UI to select a language identifier" src="https://raw.githubusercontent.com/stylelint/vscode-stylelint/main/media/language.png">

- CSS (`css`)
- HTML (`html`)
- Less (`less`)
- JavaScript (`javascript`)
- JavaScript React (`javascriptreact`)
- Markdown (`markdown`)
- [Markdown+MathML (`source.markdown.math`)](https://marketplace.visualstudio.com/items?itemName=goessner.mdmath)
- [PostCSS (`postcss`)](https://marketplace.visualstudio.com/items?itemName=mhmadhamster.postcss-language)
- [Sass (`sass`)](https://marketplace.visualstudio.com/items?itemName=Syler.sass-indented)
- SCSS (`scss`)
- styled-components
- [Official (`source.css.styled`)](https://marketplace.visualstudio.com/items?itemName=jpoissonnier.vscode-styled-components)
- [Userland (`styled-css`)](https://marketplace.visualstudio.com/items?itemName=mgmcdermott.vscode-language-babel)
- [Sugarss (`sugarss`)](https://marketplace.visualstudio.com/items?itemName=mhmadhamster.postcss-language)
- [Svelte (`svelte`)](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode)
- TypeScript (`typescript`)
- TypeScript React (`typescriptreact`)
- [Vue (`vue`, `vue-html`, `vue-postcss`)](https://marketplace.visualstudio.com/items?itemName=octref.vetur)
- XML (`xml`)
- XSL (`xsl`)

### Extension settings
Once a user follows [the stylelint startup guide](https://stylelint.io/user-guide/get-started) by creating a [configuration](https://stylelint.io/user-guide/configuration) file or by editing [`stylelint.*` VSCode settings](#extension-settings), stylelint automatically validates CSS and [PostCSS](https://marketplace.visualstudio.com/items?itemName=mhmadhamster.postcss-language) with [language identifiers](https://code.visualstudio.com/docs/languages/overview#_language-id) `css` and `postcss`, respectively.

Though relying on a [stylelint configuration file](https://stylelint.io/user-guide/configure) in your project is highly recommended, you can instead use the following extension [settings](https://code.visualstudio.com/docs/getstarted/settings):
<img width="430" alt="Screenshot of UI to select a language identifier" src="https://raw.githubusercontent.com/stylelint/vscode-stylelint/main/media/language.png">

#### stylelint.enable
_The UI to select a language identifier._

Type: `boolean`
Default: `true`
## Migrating from vscode-stylelint 0.x/Stylelint 13.x

Controls whether this extension is enabled or not.
### Stylelint 13.x and Prior is No Longer Supported

#### stylelint.configOverrides
vscode-stylelint 1.x expects to use Stylelint 14 at minimum. Usage with prior versions of Stylelint is not supported nor recommended. If you want to continue using this extension, upgrade your copy of Stylelint to version 14 or later.

Type: `Object`
Default: `null`
The `syntax` and `configOverrides` options have been removed from Stylelint 14 and this extension. See the next section for information on how to use different syntaxes.

Sets the stylelint [`configOverrides`](https://stylelint.io/user-guide/usage/node-api#configoverrides) option.
### Stylelint is No Longer Bundled

#### stylelint.config
Unlike in 0.x, 1.x no longer provides a copy of Stylelint bundled with the extension. Bundling Stylelint brought up many unwanted side effects and significantly increased the extension's size.

Type: `Object`
Default: `null`
Starting with 1.x, vscode-stylelint will depend on having a copy of Stylelint installed in the open workspace (recommended) or globally (not recommended). If the extension doesn't seem to be linting any documents, make sure you have Stylelint installed.

Sets the stylelint [`config`](https://stylelint.io/user-guide/usage/node-api#config) option. Note that when this option is enabled, stylelint doesn't load configuration files.
### Only CSS and PostCSS are Validated by Default

#### stylelint.configFile
The 0.x versions of this extension, which used Stylelint 13.x and prior, supported validating many different languages out of the box without any additional configuration. However, this added a lot of complexity and resulted in many cases of unwanted or unexpected behaviour.

Type: `string`
Default: `""`
In current versions of the extension, the extension only supports validating CSS and PostCSS out of the box and requires additional configuration to validate other languages. You will need to:

Sets the stylelint [`configFile`](https://stylelint.io/user-guide/usage/options#configfile) option. Path to a JSON, YAML, or JS file that contains your configuration object. Use this option if you don't want stylelint to search for a configuration file.
- Install the PostCSS syntax for the language you want to validate into your workspace (e.g. [postcss-html](https://www.npmjs.com/package/postcss-html) or [postcss-scss](https://www.npmjs.com/package/postcss-scss)).
- Configure Stylelint to use the syntax by providing it with the module name in the [`customSyntax` option](https://stylelint.io/user-guide/usage/options/#customsyntax) using overrides (or use the corresponding option [in this extension's settings](#stylelint.customSyntax)).

#### stylelint.configBasedir
Example Stylelint config:

Type: `string`
Default: `""`
```js
module.exports = {
overrides: [
{
files: ["**/*.scss"],
customSyntax: "postcss-scss"
}
]
};
```

Sets the stylelint [`configBasedir`](https://stylelint.io/user-guide/usage/options#configbasedir) option. The path to the directory to which relative paths defining "extends" and "plugins" are relative. Only necessary if these values are relative paths.
- [Add the language identifiers](#stylelint.validate) for the documents you want to validate to the extension's workspace or user settings.

Example VS Code config:

```json
{
"stylelint.validate": ["css", "scss"]
}
```

## Extension Settings

Though relying on a [stylelint configuration file](https://stylelint.io/user-guide/configure) in your project is highly recommended, you can instead use the following extension [settings](https://code.visualstudio.com/docs/getstarted/settings):

### `stylelint.enable`

> Type: `boolean`
> Default: `true`
Controls whether this extension is enabled or not.

### `stylelint.config`

> Type: `Object`
> Default: `null`
#### stylelint.syntax
Sets the stylelint [`config`](https://stylelint.io/user-guide/usage/node-api#config) option. Note that when this option is enabled, stylelint doesn't load configuration files.

### `stylelint.configFile`

Type: `"css" | "css-in-js" | "html" | "less" | "markdown" | "sass" | "scss" | "sugarss"`
Default: `""`
> Type: `string`
> Default: `""`
Sets the stylelint [`configFile`](https://stylelint.io/user-guide/usage/options#configfile) option. Path to a JSON, YAML, or JS file that contains your configuration object. Use this option if you don't want stylelint to search for a configuration file.

Sets the stylelint [`syntax`](https://stylelint.io/user-guide/usage/options#syntax) option. Only use this option if you want to force a specific syntax.
### `stylelint.configBasedir`

> Type: `string`
> Default: `""`
Sets the stylelint [`configBasedir`](https://stylelint.io/user-guide/usage/options#configbasedir) option. The path to the directory to which relative paths defining "extends" and "plugins" are relative. Only necessary if these values are relative paths.

#### stylelint.customSyntax
### `stylelint.customSyntax`

Type: `string`
Default: `""`
> Type: `string`
> Default: `""`
Sets the stylelint [`customSyntax`](https://stylelint.io/user-guide/usage/options#customsyntax) option. An absolute path to a custom [PostCSS-compatible](https://github.com/postcss/postcss#syntaxes) syntax module.

Expand All @@ -122,56 +139,56 @@ e.g.
"stylelint.customSyntax": "${workspaceFolder}/custom-syntax.js"
```

#### stylelint.ignoreDisables
### `stylelint.ignoreDisables`

Type: `boolean`
Default: `false`
> Type: `boolean`
> Default: `false`
Sets the stylelint [`ignoreDisables`](https://stylelint.io/user-guide/usage/options#ignoredisables) option. If `true`, stylelint ignores `styleline-disable` (e.g. `/* stylelint-disable block-no-empty */`) comments.

#### stylelint.reportNeedlessDisables
### `stylelint.reportNeedlessDisables`

Type: `boolean`
Default: `false`
> Type: `boolean`
> Default: `false`
Sets the stylelint [`reportNeedlessDisables`](https://stylelint.io/user-guide/usage/options#reportneedlessdisables) option. If `true`, stylelint reports errors for `stylelint-disable` comments that are not blocking a lint warning.

#### stylelint.reportInvalidScopeDisables
### `stylelint.reportInvalidScopeDisables`

Type: `boolean`
Default: `false`
> Type: `boolean`
> Default: `false`
Sets the stylelint [`reportInvalidScopeDisables`](https://stylelint.io/user-guide/usage/options#reportInvalidScopeDisables) option. If `true`, stylelint reports errors for `stylelint-disable` comments referring to rules that don't exist within the configuration object.

#### stylelint.validate
### `stylelint.validate`

Type: `string[]`
Default: `["css","html","javascript","javascriptreact","less","markdown","postcss","sass","scss","source.css.styled","source.markdown.math","styled-css","sugarss","svelte","typescript","typescriptreact","vue","vue-html","vue-postcss","xml","xsl"]`
> Type: `string[]`
> Default: `["css","postcss"]`
An array of language identifiers specifying which files to validate.

#### stylelint.stylelintPath
### `stylelint.stylelintPath`

Type: `string`
Default: `""`
> Type: `string`
> Default: `""`
Used to supply a custom path to the stylelint module.

#### stylelint.packageManager
### `stylelint.packageManager`

Type: `"npm" | "yarn" | "pnpm"`
Default: `"npm"`
> Type: `"npm" | "yarn" | "pnpm"`
> Default: `"npm"`
Controls the package manager to be used to resolve the stylelint library. This setting only has an effect if the stylelint library is resolved globally. Valid values are `"npm"` or `"yarn"` or `"pnpm"`.

#### stylelint.snippet
### `stylelint.snippet`

Type: `string[]`
Default: `["css","less","postcss","scss"]`
> Type: `string[]`
> Default: `["css","postcss"]`
An array of language identifiers specifying which files to enable snippets for.

#### editor.codeActionsOnSave
### `editor.codeActionsOnSave`

This extension provides an action that you can use with VS Code's `editor.codeActionsOnSave` setting. If provided a `source.fixAll.stylelint` property set to `true`, all auto-fixable stylelint errors will be fixed on save.

Expand Down Expand Up @@ -208,7 +225,7 @@ You can also selectively enable and disable specific languages using VS Code's l
}
```

### Commands
## Commands

This extension contributes the following commands to the command palette:

Expand Down

0 comments on commit 574a993

Please sign in to comment.