Stylelint Recommended Config for Vue

1.6.1 · active · verified Sun Apr 19

This package provides the recommended shareable Stylelint configuration specifically tailored for Vue.js single-file components. It extends the `stylelint-config-recommended` base configuration and automatically integrates `postcss-html` to enable parsing of `<style>` blocks within `.vue` files. The current stable version is 1.6.1, with releases typically occurring to align with new Stylelint versions, address Vue-specific parsing edge cases, or incorporate updates from its base configurations. Its key differentiator is providing an opinionated, out-of-the-box setup that handles the complexities of linting CSS within Vue SFCs, including support for preprocessors like SCSS when combined with additional configurations.

Common errors

```
Unknown word (CssSyntaxError)
```
cause This error typically occurs when the `customSyntax` option is not correctly applied, often because `stylelint-config-recommended-vue` is not the last configuration in the `extends` array, causing it to be overridden.

fix Ensure `"stylelint-config-recommended-vue"` (or its SCSS variant) is the **LAST** item in your `.stylelintrc.json` `extends` array.
```
Error: Cannot find module 'stylelint' or 'postcss-html'
```
cause Missing required peer dependencies. `stylelint-config-recommended-vue` relies on `stylelint` and `postcss-html` to function.

fix Install the necessary peer dependencies: `npm install --save-dev stylelint postcss-html`.

Warnings

breaking This configuration requires Stylelint v14.0.0 or higher. It is incompatible with Stylelint v13 and below, which will lead to installation or runtime errors.
Fix: Ensure your project's `stylelint` peer dependency is `^14.0.0` or higher. Update your `stylelint` package to the latest major version if it's below v14.
gotcha When combining `stylelint-config-recommended-vue/scss` with `stylelint-config-standard-scss`, some stylistic rules from `stylelint-config-standard-scss` might not behave as expected or conflict with Vue's context.
Fix: Consider using `stylelint-config-standard-vue` instead of `stylelint-config-standard-scss` for a more harmonized stylistic configuration tailored for Vue.
gotcha The Stylelint VS Code extension (`stylelint.vscode-stylelint`) does not lint `.vue` files by default. You need to explicitly configure it to validate Vue files.
Fix: Add `"vue"` to the `stylelint.validate` array in your `.vscode/settings.json` file (e.g., `"stylelint.validate": ["css", "scss", "vue"]`).

Install

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

Imports

Default Vue Configuration
```
{
    "extends": "stylelint-config-recommended-vue"
}
```
Apply this configuration in your `.stylelintrc.json` (or similar config file) to lint standard CSS in Vue Single-File Components. This automatically sets up `postcss-html` as the custom syntax.
SCSS Configuration for Vue
```
{
    "extends": "stylelint-config-recommended-vue/scss"
}
```
Use this configuration for linting SCSS within Vue SFCs. This variant requires `postcss-scss` to be installed as a dev dependency.
Extending with multiple configs (correct order)
wrong:
```
{
    "extends": [
        "stylelint-config-recommended-vue/scss",
        "stylelint-config-standard-scss"
    ]
}
```
correct:
```
{
    "extends": [
        "stylelint-config-standard-scss",
        "stylelint-config-recommended-vue/scss"
    ]
}
```
When extending multiple configurations, `stylelint-config-recommended-vue` (or its `/scss` variant) **must be the last item** in the `extends` array. This ensures its `customSyntax` option for parsing Vue files is not overridden, preventing parsing errors.

Quickstart

This quickstart sets up Stylelint with `stylelint-config-recommended-vue` for basic Vue SFC linting, including installation and a runnable script.

{
  "name": "my-vue-project",
  "version": "0.1.0",
  "devDependencies": {
    "postcss-html": "^1.0.0",
    "stylelint": "^16.0.0",
    "stylelint-config-recommended-vue": "^1.6.1"
  },
  "scripts": {
    "lint:style": "stylelint \"**/*.{vue,css,scss}\"
  }
}
// package.json

// .stylelintrc.json
{
  "extends": "stylelint-config-recommended-vue"
}

// src/App.vue
<template>
  <div class="container">
    <p>Hello Vue Stylelint!</p>
  </div>
</template>

<script>
export default {
  name: 'App'
};
</script>

<style scoped>
.container {
  color: #333;
  font-size: 16px;
  padding: 10px;
  background-color: #f0f0f0;
}
p {
  margin-bottom: 0;
}
</style>

# To run:
npm install
npm run lint:style

view raw JSON →