For AI agents: the complete documentation index is available at https://vite-plugin-stylelint.modyqyw.top/llms.txt, the full documentation bundle is available at https://vite-plugin-stylelint.modyqyw.top/llms-full.txt, and this page is available as Markdown at https://vite-plugin-stylelint.modyqyw.top/guide/options.md.
  • English
  • 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
    interface CustomOverlayOptions {
      initialIsOpen?: boolean | "error";
      position?: "tl" | "tr" | "bl" | "br";
      theme?: Partial<Record<ThemeKey, string>>;
      zIndex?: number;
    }

    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. With lintInWorker there 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.