vite-plugin-stylelint

6.1.0 verified Sat Apr 25 auth: no javascript

A Vite plugin that integrates Stylelint for linting CSS/SCSS/Less files during development and build. Current stable version 6.1.0, actively maintained with support for Vite 2–8 and Stylelint 13–17. Requires Node >=18. Key differentiator: runs linting in a worker thread for non-blocking performance, and automatically handles imported style files without extra file watchers (chokidar removed in v6). Ships TypeScript types and supports both ESM and CJS.

Common errors

error Cannot find module 'vite-plugin-stylelint' or its corresponding type declarations. ↓

cause Missing installation of the package.

fix

Run npm install vite-plugin-stylelint -D and ensure it is in your devDependencies.

error The requested module 'vite-plugin-stylelint' does not provide an export named 'stylelint' ↓

cause Attempting named import instead of default import.

fix

Use import stylelint from 'vite-plugin-stylelint' (default import).

error TypeError: stylelint is not a function ↓

cause Trying to use the plugin without calling it as a function, or incorrectly importing it.

fix

Ensure you call the default export as a function in the plugins array: stylelint().

error Error: stylelint version must be >=13 and <=16 ↓

cause Using an incompatible version of Stylelint. Plugin supports v13–16 (v17 may also work but not officially tested).

fix

Install a compatible version: npm install stylelint@^16 -D.

Warnings

breaking v6.0.0 removes chokidar and changes how imported style files are handled. Previously, chokidar watched files; now the plugin relies on Vite's module graph and transforms. ↓

fix Update your configuration: the 'chokidar' option no longer exists. If you relied on custom chokidar options, remove them.

breaking The peer dependency range expanded to include Vite 6, 7, 8 and Stylelint 17. If your project uses an older Vite or Stylelint, ensure compatibility. ↓

fix No action needed unless you pin an older version of the plugin.

deprecated Using Stylelint v13 requires @types/stylelint and postcss as peer deps. Consider upgrading to Stylelint v14+ which removes these dependencies. ↓

fix Install @types/stylelint@^13 and postcss@^7 || ^8 as devDependencies if using Stylelint v13. Better yet, upgrade Stylelint.

gotcha The plugin does not install Stylelint for you. You must install it separately and configure it with a .stylelintrc file or similar. ↓

fix Run `npm install stylelint -D` and create a stylelint configuration file.

gotcha The plugin runs linting in a worker thread. If Stylelint instance is not initialized before calling lintFiles, you may see errors. This was fixed in v6.0.0. ↓

fix Upgrade to v6.0.0 or later.

Install

npm install vite-plugin-stylelint

yarn add vite-plugin-stylelint

pnpm add vite-plugin-stylelint

Imports

stylelint

wrong

import { stylelint } from 'vite-plugin-stylelint'

correct

import stylelint from 'vite-plugin-stylelint'

Default export only. Named export does not exist.

default
wrong
```
const stylelint = require('vite-plugin-stylelint')
```
correct
```
const stylelint = require('vite-plugin-stylelint').default
```
In CJS, the default export is under .default. Direct require() returns an object with default property.
defineConfig
```
import { defineConfig } from 'vite'
```
defineConfig is from Vite, not this plugin. Common confusion.

Quickstart

Basic integration of vite-plugin-stylelint in Vite config with optional include/exclude patterns and lint-on-start disabled.

// vite.config.ts
import { defineConfig } from 'vite';
import stylelint from 'vite-plugin-stylelint';

export default defineConfig({
  plugins: [stylelint({
    // Options (optional)
    include: ['src/**/*.css', 'src/**/*.scss'],
    exclude: ['node_modules'],
    lintOnStart: false,
    emitError: true,
    emitWarning: true,
  })],
});