vite-plugin-biome

1.2.0 verified Mon Apr 27 auth: no javascript

vite-plugin-biome (v1.2.0) integrates Biome linting, formatting, and checking into the Vite dev server loop. It runs on startup and on hot module replacements, providing immediate feedback during development without separate CLI steps. Supports Biome >=1.8.0 and Vite >=4.x. Key differentiators: automatic fix application, configurable hot update modes (full or changed-only), build-fail-on-error, and extra Biome CLI argument passthrough. Ships TypeScript types.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/vite-plugin-biome/dist/index.mjs not supported. ↓

cause Using CommonJS require() on an ESM-only package.

fix

Use import biomePlugin from 'vite-plugin-biome' (ESM) or dynamic import() in CJS: const biomePlugin = (await import('vite-plugin-biome')).default;

error TypeError: biomePlugin is not a function ↓

cause Imported named export `{ biomePlugin }` instead of default.

fix

Use import biomePlugin from 'vite-plugin-biome' (default import).

error Error: Could not resolve '@biomejs/biome' (peer dependency) ↓

cause Missing required peer dependency @biomejs/biome.

fix

Run npm install -D @biomejs/biome or yarn add -D @biomejs/biome.

error Error: Biome command 'format' failed: exit code 1 ↓

cause Biome encountered a formatting error or misconfiguration in biome.json.

fix

Check Biome config (e.g., biome.json) for invalid rules or file exclusions. Run npx biome format --write . to test standalone.

error Error: Unknown argument: --changed ↓

cause Using --changed flag with Biome <1.9.0 which does not support it.

fix

Upgrade @biomejs/biome to >=1.9.0 or remove --changed from biomeAdditionalArgs.

Warnings

gotcha Default import is the only export; named import like `import { biomePlugin }` will import `undefined`. ↓

fix Use `import biomePlugin from 'vite-plugin-biome'`.

breaking Plugin is ESM-only; using `require('vite-plugin-biome')` throws ERR_REQUIRE_ESM. ↓

fix Use dynamic `import()` or switch to ESM in your project (e.g., type: 'module' in package.json).

breaking Peer dependency @biomejs/biome must be >=1.8.0; older Biome versions cause runtime errors or missing commands. ↓

fix Install @biomejs/biome@^1.8.0 as a devDependency.

gotcha Setting `failOnError: true` may cause unexpected build failures during development if Biome reports warnings or formatting issues. ↓

fix Use `failOnError: true` only for production builds (e.g., VITE_BUILD_MODE env check) to avoid blocking dev server.

gotcha `hotUpdateMode: 'changed'` still runs a full startup scan; only HMR triggers are scoped to changed files. Expect full scan on dev start. ↓

fix Accept startup behavior; if you need to avoid startup scan, configure `files` selectively (e.g., `files: 'src'`).

Install

npm install vite-plugin-biome

yarn add vite-plugin-biome

pnpm add vite-plugin-biome

Imports

default
wrong
```
const biomePlugin = require('vite-plugin-biome')
```
correct
```
import biomePlugin from 'vite-plugin-biome'
```
ESM-only package; CommonJS require() fails. Use dynamic import() if needed in CJS context.

default

wrong

import { biomePlugin } from 'vite-plugin-biome'

correct

import biomePlugin from 'vite-plugin-biome'

The package exports a single default function, not a named export.

type Options
wrong
```
import { Options } from 'vite-plugin-biome'
```
correct
```
import type { Options } from 'vite-plugin-biome'
```
Options interface is exported as a type; use `import type` in TypeScript to avoid runtime errors.

default (require)

wrong

const biomePlugin = require('vite-plugin-biome')

correct

const biomePlugin = (await import('vite-plugin-biome')).default

In CJS, use dynamic import() and take .default. Direct require() throws ERR_REQUIRE_ESM.

Quickstart

Minimal Vite config enabling Biome check with auto-fix on all source files during dev.

// vite.config.ts
import { defineConfig } from 'vite';
import biomePlugin from 'vite-plugin-biome';

export default defineConfig({
  plugins: [
    biomePlugin({
      mode: 'check',
      files: 'src/**/*.{js,ts,jsx,tsx}',
      applyFixes: true,
      failOnError: false,
    }),
  ],
});

// Then install peer deps:
// npm install -D vite-plugin-biome @biomejs/biome