Options
The plugin takes Stylelint shared options and its own extra options in one object. The plugin always overrides the files option.
Shared Options
The sections below cover the most common ones. The link above covers the rest.
fix
- Type:
boolean - Default:
false
Whether Stylelint rewrites the problems it can fix.
cache
- Type:
boolean - Stylelint default:
false - Plugin default:
true
Whether to enable the cache. Stylelint disables it by default. The plugin enables it for speed.
cacheLocation
- Type:
string - Default:
.stylelintcache
The path to the cache file.
Extra Options
test
- Type:
boolean - Default:
false
Whether to run Stylelint in test mode. See Command Line Interface and Configuring Vitest.
dev
- Type:
boolean - Default:
true
Whether to run Stylelint under serve. See Command Line Interface.
build
- Type:
boolean - Default:
false
Whether to run Stylelint under build. See Command Line Interface.
include
- Type:
string | string[] - Default:
["src/**/*.{css,scss,sass,less,styl,vue,svelte}"]
The files to lint. Most projects never change it. Change it only when the include and exclude ranges overlap.
With the default settings, the plugin calls stylelint.lint only in the transform hook. It builds a filter from this value. The filter decides whether to call Stylelint, and what to pass. So the value must be a valid picomatch pattern.
When lintOnStart is on, the plugin also calls stylelint.lint in the buildStart hook. There it passes the value straight through as files. So the value must also be a glob that Stylelint understands. Stylelint 18 resolves globs with tinyglobby.
When lintDirtyOnly is off, the plugin passes the value to stylelint.lint on every call. So the value must also be a glob that Stylelint understands. Stylelint 18 resolves globs with tinyglobby.
exclude
- Type:
string | string[] - Default:
['node_modules', 'virtual:']
The files not to lint. Most projects never change it. Change it only when the include and exclude ranges overlap.
The plugin always ignores the virtual module. You do not configure that here.
With the default settings, the plugin calls stylelint.lint only in the transform hook. It builds a filter from this value. The filter decides whether to call Stylelint, and what to pass. So the value must be a valid picomatch pattern.
When lintOnStart is on, or lintDirtyOnly is off, this value has no effect. To leave those files out, adjust the include value.
stylelintPath
- Type:
string - Default:
"stylelint"
The path to the Stylelint used for linting. The plugin loads it with a dynamic import. Read Vite server.fs options first.
formatter
- Type:
string - Default:
"string"
The formatter name, path or function. The plugin passes it to Stylelint's formatter option to turn lint results into a human-readable or machine-readable string.
lintInWorker
- Type:
boolean - Default:
false
Lint in a worker.
A worker keeps Vite fast. The trade-off: the build no longer stops on Stylelint errors, and Vite's native overlay is gone. The terminal still prints the errors. The custom overlay still works with lintInWorker.
vite-plugin-checker solves the same problem. Pick whichever fits your setup.
customOverlay
- Type:
boolean | CustomOverlayOptions - Default:
false
Use the plugin's custom overlay instead of Vite's native error overlay.
The native overlay renders Stylelint's ANSI-colored string output verbatim. Color is lost in the browser, or the escape codes show through. The custom overlay renders structured results natively. It also works when lintInWorker is on, which the native overlay does not.
In an environment without a DOM entry (mini-programs, SSR, headless tests), the plugin does not inject the runtime. It warns once, then prints to the terminal only.
false: keep Vite's native overlay. WithlintInWorkerthere is no overlay at all.true: use the custom overlay with default styling.{...}: use the custom overlay with the given styling.
This option applies under serve only. In build mode the native context.error blocking behavior is always preserved.
lintOnStart
- Type:
boolean - Default:
false
Lint the files matched by include once, in the buildStart hook.
Without a cache, and without lintInWorker, this makes Vite's first start noticeably slower.
lintDirtyOnly
- Type:
boolean - Default:
true
Outside the buildStart hook, lint only the files a request touches. The files matched by exclude are skipped.
When this option is off, the plugin checks files against the include and exclude values instead.
emitError
- Type:
boolean - Default:
true
Emit found errors.
emitErrorAsWarning
- Type:
boolean - Default:
false
Emit found errors as warnings. Useful while prototyping.
emitWarning
- Type:
boolean - Default:
true
Emit found warnings.
emitWarningAsError
- Type:
boolean - Default:
false
Emit found warnings as errors.