vite-plugin-checker

A Vite plugin that can run TypeScript, VLS, vue-tsc, ESLint in worker thread.

Features

• ⚡️ Speeds up TypeScript, vue-tsc, ESLint, etc. checks by running in a worker thread in serve mode
• 🍀 Works good with vanilla JS / TS, React, Vue2, Vue3
• 💬 Prompt errors in an overlay UI and terminal
• 🌗 Works both in Vite serve and build mode

History version documentations 0.1, 0.2, 0.3. It's highly recommended to use latest version before 1.0.0, although there's some breaking changes, the plugin configuration is quite simple.

Online playground

Getting Started

1. Install plugin.

   pnpm add vite-plugin-checker -D

2. Add plugin to Vite config file. Add the checker you need. We add TypeScript below as an example. See all available checkers here.

   // vite.config.js
   import checker from 'vite-plugin-checker'
   
   export default {
     plugins: [checker({ typescript: true })], // e.g. use TypeScript check
   }

3. Open localhost page and start development 🚀.

💡 Caveats:

1. It's recommended to open a browser for a better terminal flush, see #27.
2. server.ws.on is introduced to Vite in 2.6.8. vite-plugin-checker relies on server.ws.on to bring diagnostics back after a full reload and it' not available for older version of Vite.

Checker configurations

For each checker config field below:

• Set to true to use a checker with its default value (except ESLint).
• Make sure to install the peer dependencies indicated of each checker.
• Leave the field blank or false to disable the checker.
• Checker can be enabled with an advanced object config.

TypeScript

1. Make sure typescript is installed as a peer dependency.

2. Add typescript field to plugin config.

   export default {
     plugins: [checker({ typescript: true /** or an object config */ })],
   }

   Advanced object configuration table of options.typescript

   field	Type	Default value	Description
   root	string	Vite config root	Root path to find tsconfig file
   tsconfigPath	string	"tsconfig.json"	Relative tsconfig path to root
   buildMode	boolean	false	Add --build to tsc flag, note that noEmit does NOT work if buildMode is true (#36917)

vue-tsc (Volar)

1. Make sure vue-tsc & typescript are installed as a peer dependency of your Vite project.

   ⚠️ The vue-tsc version must >= 0.33.9.

   pnpm add vue-tsc@latest typescript -D

2. Add vueTsc field to plugin config.

   export default {
     plugins: [checker({ vueTsc: true /** or an object config */ })],
   }

   Advanced object configuration table of options.vueTsc

   field	Type	Default value	Description
   root	string	Vite config root	Root path to find tsconfig file
   tsconfigPath	string	"tsconfig.json"	Relative tsconfig path to root

3. (Optional for Vue2 user) The type check is powered by vue-tsc so it supports Vue2 according to the documentation, you need to install @vue/runtime-dom by yourself.

ESLint

1. Make sure eslint and related plugins for your eslintrc are installed as peer dependencies.

2. (Optional but highly recommended) Install optionator@^0.9.1 with your package manager. It's needed because of ESLint dependents on it. It's probably working fine even it's not installed as it's accessed as a phantom dependency. But when you set hoist=false of pnpm. It won't be accessible anymore without explicit installation.

3. Add eslint field to plugin config and options.eslint.lintCommand is required. The lintCommand is the same as the lint command of your project. The default root of the command uses Vite's root.

   // e.g.
   export default {
     plugins: [
       checker({
         eslint: {
           lintCommand: 'eslint "./src/**/*.{ts,tsx}"', // for example, lint .ts & .tsx
         },
       }),
     ],
   }

   Advanced object configuration table of options.eslint

   field	Type	Default value	Description
   lintCommand	string	This value is required	lintCommand will be executed at build mode, and will also be used as default config for dev mode when eslint.dev.eslint is nullable.
   dev.overrideConfig	ESLint.Options	undefined	(Only in dev mode) You can override the options of the translated from lintCommand. Config priority: const eslint = new ESLint({cwd: root, ...translatedOptions, ...pluginConfig.eslint.dev?.overrideConfig, }).
   dev.logLevel	('error' | 'warning')[]	['error', 'warning']	(Only in dev mode) Which level of ESLint should be emitted to terminal and overlay in dev mode

vls (Vetur)

1. Make sure vls is installed as a peer dependency, plugin will use vls as the check server.

   pnpm add vls -D

2. Add vls field to plugin config.

   module.exports = {
     plugins: [checker({ vls: true })],
   }

   Advanced object configuration of options.vls

   VLS configuration accepts the same values that can be configured in VS code with keys that start with vetur. These are configured with nested objects rather than dotted string notation. TypeScript intellisense is available.

   See initParams.ts for a comprehensive list of the defaults that can be overridden. Unfortunately, Vetur does not provide a single comprehensive document of all its options.

   For example, to performing checking only the <script> block:

   checker({
     vls: {
       vetur: {
         validation: {
           template: false,
           templateProps: false,
           interpolation: false,
           style: false,
         },
       },
     },
   }),

Shared configuration

Below is some common configuration to control the behaviors of the plugin.

{
  /**
   * Show overlay on UI view when there are errors or warnings in dev mode.
   * - Set `true` to show overlay
   * - Set `false` to disable overlay
   * - Set with a object to customize overlay
   *
   * @defaultValue `true`
   */
  overlay:
    | boolean
    | {
        /**
         * Set this true if you want the overlay to default to being open if errors/warnings are found
         * @defaultValue `true`
         */
        initialIsOpen?: boolean
        /**
         * The position of the vite-plugin-checker badge to open and close the diagnostics panel
         * @default `bl`
         */
        position?: 'tl' | 'tr' | 'bl' | 'br'
        /**
         * Use this to add extra style to the badge button, see details of [Svelte style](https://svelte.dev/docs#template-syntax-element-directives-style-property)
         * For example, if you want to hide the badge, you can pass `display: none;` to the badgeStyle property
         */
        badgeStyle?: string
      }
  /**
   * stdout in terminal which starts the Vite server in dev mode.
   * - Set `true` to enable
   * - Set `false` to disable
   *
   * @defaultValue `true`
   */
  terminal: boolean
  /**
   * Enable checking in build mode
   * @defaultValue `true`
   */
  enableBuild: boolean
}

Playground

Run projects in playground/* to try it out.

pnpm i
pnpm run build
cd ./playground/<one_exapmple>    # choose one example
pnpm run dev                      # test in serve mode
pnpm run build                    # test in build mode

License

MIT License © 2022 fi3ework