vite-plugin-eslint2

English

简体中文

English

简体中文

Appearance

Options ​

You can pass ESLint Node.js API constructor options to the plugin, or you can pass the extra options.

Constructor Options ​

Common options and descriptions are listed below, complete links are provided above.

fix ​

  • Type: boolean
  • Default: false

Whether to automatically fix.

cache ​

  • Type: boolean
  • ESLint default: false
  • Plugin default: true

Whether to enable the cache. This is disabled in ESLint by default and enabled in plugin by default to improve speed.

cacheLocation ​

  • Type: string
  • Default: .eslintcache

The path to the cache.

Extra Options ​

Extra options and explanations are listed below.

test ​

  • Type: boolean
  • Default: false

Whether to run ESLint under test mode. See Command Line Interface and Configuring Vitest for more.

dev ​

  • Type: boolean
  • Default: true

Whether to run ESLint under serve command. See Command Line Interface for more.

build ​

  • Type: boolean
  • Default: false

Whether to run ESLint under build command. See Command Line Interface for more.

include ​

  • Type: string | string[]
  • Default: ['src/**/*.{js,jsx,ts,tsx,vue,svelte}']

This option specifies the files you want to lint. You don't need to change it in most cases, unless the include and exclude ranges overlap.

If you're using the plugin defaults, the plugin will only call eslint.lintFiles in the transform hook. The option value will be used to create a filter to determine if the call should be made and the parameter of the call, which means that the option value needs to fulfill the requirements of picomatch@2.3.1.

If you enable the lintOnStart option, the plugin will also call eslint.lintFiles in the buildStart hook. The option value will not be used to create a filter, but will be used directly as the call parameter, which means that the option value also needs to fulfill the minimatch@3.1.2 requirement.

If you disable the lintDirtyOnly option, the plugin will use the option value as the call parameter when it calls eslint.lintFiles outside of the buildStart lifecycle. This means that this option value also needs to fulfill the requirements of minimatch@3.1.2.

exclude ​

  • Type: string | string[]
  • Default: ['node_modules', 'virtual:']

This option specifies the files you don't want to lint. You don't need to change it in most cases, unless the include and exclude ranges overlap.

The plugin forces the virtual module to be ignored and you don't need to do any configuration related to it here.

If you're using the plugin defaults, the plugin will only call eslint.lintFiles in the transform hook. The option value will be used to create a filter to determine if the call should be made and the parameter of the call, which means that the option value needs to fulfill the requirements of picomatch@2.3.1.

If you enable the lintOnStart option or disable the lintDirtyOnly option, the option value will not take effect. You need to change include value to include this option value.

eslintPath ​

  • Type: string
  • Default: "eslint"

Path to ESLint that will be used for linting. Use dynamic import under the hood. Read server.fs first.

If you want to use the flat config system in ESLint v8, set the value to 'eslint/use-at-your-own-risk'. Place a flat config file in the root of your project or set the ESLINT_USE_FLAT_CONFIG environment variable to true and pass the option overrideConfigFile to the plugin if you are using other config files.

You can learn more from Flat config rollout plans and Configuration Files (New).

Since ESLint v10.0.0, the flat config system is enforced and the 'eslint/use-at-your-own-risk' option is no longer provided. You can learn more form ESLint v10.0.0 released.

formatter ​

  • Type: string
  • Default: "stylish"

The name or the path of a formatter. This is used to load a formatter in order to convert lint results to a human- or machine-readable string.

lintInWorker ​

  • Type: boolean
  • Default: false

Lint in worker. This is disabled by default.

When lint in worker, Vite build process will be faster. You will not see Vite error overlay, Vite build process will not be stopped, even with errors shown in terminal.

It is similar with @nabla/vite-plugin-eslint and vite-plugin-checker, but @nabla/vite-plugin-eslint only supports linting in worker, vite-plugin-checker can show you errors and warnings in browsers.

customOverlay ​

  • Type: false | true | CustomOverlayOptions
  • Default: false

Use the plugin's custom overlay instead of Vite's native error overlay. The native overlay renders ESLint's ANSI-colored stylish output verbatim, which loses color (or shows escape codes) in the browser. The custom overlay renders structured results natively and — unlike the native overlay — also works when lintInWorker is enabled.

  • false: keep Vite's native overlay (current behavior; no overlay in worker mode).
  • true: use the custom overlay with default styling.
  • {...}: use the custom overlay with the given styling.

Only takes effect under serve. In build mode the native context.error blocking behavior is always preserved.

In environments without a DOM entry (mini-programs, SSR, headless tests), the runtime is not injected; the plugin warns once and falls back to terminal-only output.

js
eslint({
  customOverlay: true,
});
// or with styling
eslint({
  customOverlay: {
    position: "tl",
    initialIsOpen: true,
    zIndex: 99999,
    theme: {
      "--vite-plugin-eslint2-bg": "#1a1a2e",
      "--vite-plugin-eslint2-panel-bg": "#16213e",
      "--vite-plugin-eslint2-error": "#ff6b6b",
    },
  },
});

customOverlay.position ​

  • Type: "tl" | "tr" | "bl" | "br"
  • Default: "br"

Position of the overlay badge/panel on the viewport.

customOverlay.initialIsOpen ​

  • Type: boolean | "error"
  • Default: "error"

Whether the panel starts open. "error" opens only when there is at least one error.

customOverlay.zIndex ​

  • Type: number
  • Default: 99998

z-index of the overlay. Exposed because Design Systems may occupy high z-index layers.

customOverlay.theme ​

  • Type: Partial<Record<ThemeKey, string>>

Override the overlay's CSS variables. Keys are the predefined variable names:

  • --vite-plugin-eslint2-bg
  • --vite-plugin-eslint2-panel-bg
  • --vite-plugin-eslint2-error
  • --vite-plugin-eslint2-warning
  • --vite-plugin-eslint2-text
  • --vite-plugin-eslint2-font-mono
  • --vite-plugin-eslint2-radius

lintOnStart ​

  • Type: boolean
  • Default: false

Lint include option specified files once in buildStart hook to find potential errors. This is disabled by default.

This will significantly slow down Vite first starting if you have no caches and don't enable lintInWorker.

lintDirtyOnly ​

  • Type: boolean
  • Default: true

Whether or not to checkout only modified files that are not included in the exclude option value when running ESLint outside of the buildStart lifecycle. Enabled by default.

When disabled, files are checked against the include and exclude option values.

emitError ​

  • Type: boolean
  • Default: true

Emit found errors. This is enabled by default.

emitErrorAsWarning ​

  • Type: boolean
  • Default: false

Emit found errors as warnings. This is disabled by default but you may want it enabled when prototyping.

emitWarning ​

  • Type: boolean
  • Default: true

Emit found warnings. This is enabled by default.

emitWarningAsError ​

  • Type: boolean
  • Default: false

Emit found warnings as errors when enabled. This is disabled by default.