Vite Plugin Checker

Common errors

• Error: require() of ES Module ... is not supported. Instead change the require of ... to a dynamic import()

  cause Attempting to use `require()` to import `vite-plugin-checker` in a CommonJS context.
  fix Migrate your Vite configuration file (`vite.config.js` or `vite.config.ts`) to use ES module syntax (`import ... from '...'`). Ensure `package.json` has `"type": "module"` if not using `.mjs` file extension.

• No ESLint output found. Please make sure ESLint is configured correctly.

  cause ESLint is either not installed, not configured, or the `lintCommand` in `checker` options is incorrect or points to non-existent files.
  fix Verify ESLint is installed (`npm install -D eslint`). Check your `.eslintrc.*` configuration. Ensure the `lintCommand` in `vite-plugin-checker` accurately targets your source files (e.g., `eslint "./src/**/*.{js,jsx,ts,tsx,vue}"`).

• TypeScript checker is not running. Did you install `typescript`?

  cause TypeScript is not installed in the project or `typescript: true` is enabled in checker options without a valid `tsconfig.json`.
  fix Install TypeScript (`npm install -D typescript`). Ensure a `tsconfig.json` file exists in your project root with correct configuration.

• TypeError: Cannot read properties of undefined (reading 'Diagnostics') when using `vue-tsc`.

  cause Incompatible versions of `vue-tsc` and `vite-plugin-checker`, or incorrect configuration for `vue-tsc`.
  fix Ensure `vue-tsc` is installed (`npm install -D vue-tsc`). Check the `peerDependencies` of `vite-plugin-checker` for compatible `vue-tsc` versions. Try enabling `vueTsc: true` in the checker options.

• ERROR: Failed to load config "prettier" from "eslint-config-prettier"

  cause A common issue where ESLint or other linters cannot find their required configurations or plugins, often due to missing installations or incorrect paths.
  fix Ensure all ESLint/Stylelint/Biome configurations and their respective plugins are correctly installed as dev dependencies. For example, `npm install -D eslint-config-prettier` if that's the missing piece. Double-check your config files (`.eslintrc`, `.stylelintrc`, `biome.json`) for correct `extends` paths.

Warnings

• breaking The plugin dropped support for CommonJS (CJS) usage. Projects must use ES Modules (ESM) for importing and configuring the plugin.
  Fix: Ensure your `vite.config.js` or `vite.config.ts` uses ESM syntax (e.g., `import` statements) and your `package.json` specifies `"type": "module"` or uses `.mjs` files for configuration if needed.
• breaking The internal dependency `strip-ansi` was replaced with Node's built-in functionality. While this is unlikely to directly break user code, it signals an internal refactor that might have subtle impacts or require specific Node.js versions.
  Fix: Ensure your Node.js version meets the minimum requirement (`>=16.11`). Update `vite-plugin-checker` and related dependencies to their latest compatible versions.
• gotcha Requires specific versions of peer dependencies like `@biomejs/biome`, `eslint`, `stylelint`, `typescript`, `vite`, `vue-tsc`, etc. Mismatched versions can lead to errors or the checker not functioning correctly.
  Fix: Always install peer dependencies explicitly at compatible versions. Refer to `package.json`'s `peerDependencies` range or the plugin's documentation for the exact compatible versions.
• breaking Upgrade to `chokidar v4` introduced potential breaking changes due to how file watching is handled. This might affect performance or specific watch configurations.
  Fix: Review any custom file watching configurations you might have. If issues arise, consult `chokidar`'s v4 migration guide and `vite-plugin-checker`'s documentation. Ensure `vite-plugin-checker` is updated to a version compatible with your `chokidar` setup, or let the plugin manage `chokidar` versions.
• gotcha ESLint v10.x introduced breaking changes. While `vite-plugin-checker` adds support for ESLint v10.x, older configurations or ESLint plugins might not be compatible.
  Fix: If upgrading ESLint to v10, ensure all your ESLint configurations and plugins are also compatible with v10. Consult the ESLint v10 migration guide. Update `vite-plugin-checker` to version 0.13.0 or newer for official support.

Install

• npm install vite-plugin-checker npm
• yarn add vite-plugin-checker yarn
• pnpm add vite-plugin-checker pnpm

Imports

• checker
  wrong:

  const checker = require('vite-plugin-checker')

  correct:

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

  The `checker` function is the main export. Since v0.9.0, only ESM imports are supported.
• UserConfig

  import type { UserConfig } from 'vite'

  When configuring in `vite.config.ts`, you typically import `UserConfig` from `vite` itself, not the plugin.
• CheckerOptions
  wrong:

  import { CheckerOptions } from 'vite-plugin-checker'

  correct:

  import type { CheckerOptions } from 'vite-plugin-checker'

  CheckerOptions is a type for configuring the plugin. Use `import type` for type-only imports to prevent bundling issues and improve tree-shaking.

Quickstart

This quickstart demonstrates how to integrate `vite-plugin-checker` into a Vite project with Vue and TypeScript, enabling both TypeScript type checking and ESLint linting. It shows the basic configuration for adding the plugin to `vite.config.ts`.

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { checker } from 'vite-plugin-checker';

export default defineConfig({
  plugins: [
    vue(),
    checker({
      typescript: true, // Enable TypeScript type checking
      eslint: {
        lintCommand: 'eslint "./src/**/*.{js,jsx,ts,tsx,vue}"', // ESLint command
      },
      // biome: {
      //   lintCommand: 'biome check --write --no-errors-on-unmatched --files-ignore-unknown=true .',
      // },
      // stylelint: {
      //   lintCommand: 'stylelint "./src/**/*.{css,scss,vue}"',
      // },
      // vueTsc: true, // Enable vue-tsc if using Vue 3
    }),
  ],
  server: {
    // Optional: Configure the server to display overlay for errors
    overlay: {
      initialIsOpen: false,
      // Make sure the checker overlay doesn't conflict with Vite's own overlay
    },
  },
});