Migrating to v1

This guide covers upgrading from vite-plugin-checker 0.14 to 1.0. Most projects only need to check their Node.js version. The other changes affect specific checkers or setups; each section says who it applies to.

If you're upgrading from an earlier 0.x release, read the release notes for each version in between as well.

Node.js 22.22 or later is required

vite-plugin-checker now requires Node.js ^22.22.0 or >=24.11.0. Node.js 20 is no longer supported.

Migration: upgrade Node.js locally and in CI.

Build commands run without a shell

In build mode, checker commands used to be passed to a shell as one string. This split paths that contain spaces into several arguments. Commands now run directly, with arguments parsed in a quote-aware way.

This affects you if your lintCommand, or Biome or svelte-check flags, rely on shell features:

• Unquoted globs such as eslint src/**/*.ts are no longer expanded by the shell. ESLint and Stylelint expand quoted globs themselves.
• Shell syntax such as &&, pipes, redirects, and $VARIABLE expansion isn't available.

Migration: quote globs, and move any shell logic into a package.json script that you run separately:

checker({
  eslint: {
    lintCommand: 'eslint "./src/**/*.{ts,tsx}"',
  },
})

Build commands run from the Vite root

Build mode checks used to run from the current working directory. They now run from the Vite root, or from the plugin's root option if you set it. This matches dev mode.

This affects you if your Vite root differs from the directory you run vite build in, and your lintCommand or flags use relative paths.

Migration: make relative paths in lintCommand and flags relative to the Vite root, or set the plugin's root option.

Solution-style tsconfigs use build mode automatically

The TypeScript and vue-tsc checkers now enable buildMode automatically when the tsconfig is solution-style: "files": [] with references, as generated by create-vite and create-vue. Previously these tsconfigs checked no files.

Migration: none needed in most cases. To keep the previous behavior, set buildMode: false.

Biome uses build.command and build.flags in build mode

The biome.build.command and biome.build.flags options were documented but ignored; build mode always used the top-level command and flags. They now take effect.

Migration: if you set build.command or build.flags, check that they're the values you want in build mode.

Biome also ignores --reporter and --reporter-file in dev mode flags now, because the checker reads Biome's JSON output. Set a reporter for build mode with build.flags instead.

Stylelint applies dev.overrideConfig on every lint

stylelint.dev.overrideConfig used to apply only to the first lint when the dev server started. Files re-linted after a change used the options translated from lintCommand. The override now applies to every lint.

Migration: none, unless you relied on the override applying only at startup.

The overlay loads through the Vite client

The overlay runtime used to be injected into index.html. It now loads through the Vite client, so it also appears on pages that SSR frameworks render, such as Nuxt, SvelteKit, and TanStack Start.

Migration: if you added the /@vite-plugin-checker-runtime-entry script manually to a page that also loads /@vite/client, you can remove it. Keeping it is harmless; the overlay is only added once.

Next steps

• Dev and build modes: review how checks run in each mode.
• Checkers overview: check the options for the checkers you use.