Standard Stylelint Config for Vue

1.0.0 · active · verified Sun Apr 19

stylelint-config-standard-vue is a shareable Stylelint configuration tailored for Vue.js projects. Its current stable version is 1.0.0, released in January 2022. As a configuration package, its release cadence is typically tied to updates in Stylelint and its foundational configurations like `stylelint-config-standard` and `stylelint-config-recommended-vue`. This config stands out by combining general CSS best practices with specific adjustments for Vue Single File Components (SFCs), including support for SCSS stylesheets within Vue components. It ensures consistent styling by extending a robust set of rules and requires Stylelint v14 or newer for compatibility, as older versions do not handle non-CSS syntaxes like HTML/Vue natively.

Common errors

```
Configuration Error: You must install 'postcss-html' as a peer dependency.
```
cause The `postcss-html` package, required for parsing Vue files, is not installed or its version is incompatible.

fix Install `postcss-html` as a dev dependency: `npm install --save-dev postcss-html`.
```
Unknown word (CssSyntaxError) in Vue files.
```
cause Stylelint is unable to correctly parse the CSS content within your Vue Single File Components. This often happens if `postcss-html` is missing, Stylelint is an old version (<14), or if `stylelint-config-standard-vue` is not the last item in the `extends` array when multiple configs are used.

fix Ensure `stylelint` is v14+, `postcss-html` is installed, and `stylelint-config-standard-vue` is the last item in your `extends` array if other configs use `customSyntax`.
```
VS Code is not highlighting or fixing Stylelint issues in my .vue files.
```
cause The Stylelint VS Code extension needs to be explicitly told to validate Vue files.

fix Add `"vue"` to the `stylelint.validate` setting in your `.vscode/settings.json` file. You may also want to disable built-in CSS/SCSS validation to avoid conflicts.

Warnings

breaking This configuration requires Stylelint v14.0.0 or higher. It is incompatible with Stylelint v13 and below due to significant changes in how Stylelint handles non-CSS syntaxes like HTML/Vue in v14.
Fix: Upgrade Stylelint to version 14 or newer (`npm install stylelint@latest`).
gotcha When using multiple Stylelint configurations that include a `customSyntax` option (such as `stylelint-config-standard-vue` which bundles `postcss-html`), the configuration specifying the `customSyntax` must be the LAST item in the `extends` array. Failing to do so can lead to parsing errors like 'Unknown word (CssSyntaxError)'.
Fix: Ensure `stylelint-config-standard-vue` or `stylelint-config-vue/scss` is the final entry in your `extends` array if other configs also set `customSyntax`.
gotcha Linting of `.vue` files in Visual Studio Code with the official Stylelint extension requires explicit configuration. The extension does not validate `*.vue` files by default.
Fix: Add `"vue"` to the `stylelint.validate` array in your `.vscode/settings.json` file.
gotcha When combining `stylelint-config-standard-vue/scss` with `stylelint-config-standard-scss`, `stylelint-config-standard-scss` must appear *before* the Vue-specific SCSS config in the `extends` array.
Fix: Order your `extends` array like this: `["stylelint-config-standard-scss", "stylelint-config-standard-vue/scss"]`.

Install

npm install stylelint-config-standard-vue npm
yarn add stylelint-config-standard-vue yarn
pnpm add stylelint-config-standard-vue pnpm

Imports

stylelint-config-standard-vue
wrong:
```
import config from 'stylelint-config-standard-vue';
```
correct:
```
{ "extends": "stylelint-config-standard-vue" }
```
This package is a Stylelint configuration, not a JavaScript module. It is consumed via the `extends` property in a Stylelint configuration file (e.g., `.stylelintrc.json` or `stylelint.config.js`).
stylelint-config-standard-vue/scss
wrong:
```
{ "extends": "stylelint-config-standard-vue/scss" } // without stylelint-config-standard-scss
```
correct:
```
{ "extends": ["stylelint-config-standard-scss", "stylelint-config-standard-vue/scss"] }
```
For SCSS support within Vue files, this extension should be used *after* `stylelint-config-standard-scss` in the `extends` array to ensure correct rule application.
stylelint-config-html/vue
wrong:
```
{ "customSyntax": "postcss-html" }
```
correct:
```
{ "extends": "stylelint-config-html/vue" }
```
Use `stylelint-config-html/vue` if you only need the parser for Vue files without the specific rules of `stylelint-config-standard-vue`. This is useful for building a custom config from scratch or avoiding rule overrides.

Quickstart

Installs the necessary packages, configures Stylelint to use the standard Vue rules, and sets up VS Code for proper linting of `.vue` files.

npm install --save-dev stylelint postcss-html stylelint-config-standard-vue

// .stylelintrc.json
{
  "extends": "stylelint-config-standard-vue",
  "overrides": [
    {
      "files": ["*.vue", "**/*.vue"],
      "rules": {
        // Example: override a rule for Vue files
        "indentation": 2
      }
    }
  ]
}

// .vscode/settings.json (for VS Code integration)
{
  "stylelint.validate": [
    "css",
    "scss",
    "less",
    "postcss",
    "vue" // Add 'vue' language to enable linting in .vue files
  ],
  "css.validate": false, // Optional: disable built-in CSS validation to avoid conflicts
  "scss.validate": false
}

view raw JSON →