vite-plugin-linter

4.0.0 verified Mon Apr 27 auth: no javascript

Vite plugin that integrates ESLint and TypeScript linting into the Vite dev server and build process, displaying linter output in both the terminal and browser console. Version 4.0.0 is the latest stable release. Key differentiators: uses Vite's configureServer hook for real-time console feedback, supports custom linters, and provides separate serve/build options. Requires Vite and ESLint/TypeScript as peer dependencies.

Common errors

error Error: configEnv is required ↓

cause EsLinter instantiated without passing the Vite ConfigEnv object.

fix

Ensure EsLinter is constructed within the defineConfig callback and configEnv is passed: new EsLinter({ configEnv })

error TypeError: Cannot read properties of undefined (reading 'includes') ↓

cause Plugin options include field is not an array or is undefined.

fix

Set include option as an array of patterns: include: ['./src/**/*.ts', './src/**/*.tsx']

error Error: Could not find tsconfig.json ↓

cause TypeScriptLinter default configFilePath is tsconfig.json but it does not exist in project root.

fix

Either create tsconfig.json or specify configFilePath: new TypeScriptLinter({ configFilePath: './otherTsconfig.json' })

error Warning: Linter output injected into first non-node_modules file ↓

cause Plugin injects output into the first file not in node_modules; if no such file exists, injection fails.

fix

Ensure there is at least one source file outside node_modules, or explicitly set injectFile option.

Warnings

gotcha Plugin uses Vite-specific hook configureServer and will not work with Rollup. ↓

fix Use only with Vite; if migrating to Rollup, consider @rollup/plugin-eslint or similar.

gotcha EsLinter requires configEnv from defineConfig callback; not providing it causes runtime errors. ↓

fix Pass configEnv as shown in documentation; it is required for ESLint configuration resolution.

gotcha When running via CLI (vite-plugin-linter command), includeMode always defaults to filesInFolder, which may lint all files and cause performance issues. ↓

fix Use the CLI only for pre-commit hooks or small projects; adjust include/exclude patterns if needed.

deprecated Options deprecated in previous versions may still work but will be removed in future releases. ↓

fix Check CHANGELOG for any deprecated options; migrate to new API.

gotcha Default include is undefined, which may lint all processed files; unexpected large linting sets can slow down builds. ↓

fix Explicitly set include patterns to limit scope.

Install

npm install vite-plugin-linter

yarn add vite-plugin-linter

pnpm add vite-plugin-linter

Imports

linterPlugin

wrong

import linterPlugin from 'vite-plugin-linter'

correct

import { linterPlugin } from 'vite-plugin-linter'

Named export; default import will not work.

EsLinter

wrong

import { ESLinter } from 'vite-plugin-linter'

correct

import { EsLinter } from 'vite-plugin-linter'

Export name is 'EsLinter' (not 'ESLinter').

TypeScriptLinter

wrong

import { TypeScriptLinter } from 'vite-plugin-linter/ts'

correct

import { TypeScriptLinter } from 'vite-plugin-linter'

All exports are from the main package; no subpath exports.

Quickstart

Sets up ESLint and TypeScript linting with default options for files in src directory.

import { defineConfig } from 'vite';
import { linterPlugin, EsLinter, TypeScriptLinter } from 'vite-plugin-linter';

export default defineConfig((configEnv) => ({
  plugins: [
    linterPlugin({
      include: ['./src/**/*.ts', './src/**/*.tsx'],
      linters: [new EsLinter({ configEnv }), new TypeScriptLinter()],
    }),
  ],
}));