vite-plugin-oxlint

2.1.1 verified Sat Apr 25 auth: no javascript

Vite plugin that integrates Oxlint, a fast Rust-based linter, into Vite build and dev workflows. Current stable version 2.1.1, release cadence is irregular with breaking changes in 2.0.0. Key differentiators: leverages Oxlint's performance (50-100x faster than ESLint), supports HMR linting (lintOnHotUpdate), and offers fine-grained control via options (failOnError, failOnWarning, deny/allow/warn rules). Active maintenance, peer dependencies require oxlint >=0.9.0 and Vite >=5.0.0.

Common errors

error ERR_REQUIRE_ESM: require() of ES Module /path/to/node_modules/vite-plugin-oxlint/dist/index.js from not supported. ↓

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

fix

Switch to import statement or use dynamic import().

error Error: Cannot find module 'oxlint' (or 'vite-plugin-oxlint' is not a peer dependency) ↓

cause Missing oxlint peer dependency; oxlint binary not installed or not found.

fix

Run npm install oxlint --save-dev (or yarn add oxlint --dev).

error Error: Oxlint binary not found at path 'path/to/oxlint'. Check oxlintPath option. ↓

cause The oxlintPath points to a non-existent or non-executable file.

fix

Ensure oxlintPath is an absolute path to the oxlint binary. Use which oxlint to locate global install.

Warnings

breaking v2.0.0 migrated from CommonJS to ESM-only. Require() will throw. ↓

fix Use import statements in your project (set type: module in package.json or use .mjs files).

gotcha oxlint binary path must be absolute if specified, otherwise plugin may pick global install incorrectly. ↓

fix Set oxlintPath to an absolute path using path.resolve() or __dirname.

gotcha failOnError and failOnWarning default to false; build succeeds even with lint errors unless explicitly set. ↓

fix Set failOnError: true and/or failOnWarning: true to enforce lint pass.

gotcha The 'params' option passes raw CLI flags; malformed or conflicting flags can cause silent failures or unexpected behavior. ↓

fix Avoid using params unless necessary; prefer built-in options like allow, deny, warn, format.

deprecated The 'quiet' option suppresses warnings but may be deprecated in future in favor of 'failOnWarning: false' pattern. ↓

fix Use failOnWarning: false (default) to allow warnings without failing the build.

Install

npm install vite-plugin-oxlint

yarn add vite-plugin-oxlint

pnpm add vite-plugin-oxlint

Imports

default

wrong

const oxlintPlugin = require('vite-plugin-oxlint')

correct

import oxlintPlugin from 'vite-plugin-oxlint'

ESM-only package since v2.0.0; CommonJS require will fail

OxlintPluginOptions

wrong

import { OxlintPluginOptions } from 'vite-plugin-oxlint'

correct

import type { OxlintPluginOptions } from 'vite-plugin-oxlint'

TypeScript type import only; not a runtime export

OxlintPluginUserConfig
```
import type { OxlintPluginUserConfig } from 'vite-plugin-oxlint'
```
Alternative exported type for user-facing options

Quickstart

Configures vite-plugin-oxlint to lint ./src on start and during HMR, ignoring tests, allowing no-unused-vars, denying no-console, warning on eqeqeq, and failing build on errors.

// vite.config.js
import oxlintPlugin from 'vite-plugin-oxlint'

export default {
  plugins: [
    oxlintPlugin({
      path: './src',
      failOnError: true,
      lintOnStart: true,
      lintOnHotUpdate: true,
      ignorePattern: 'tests/**',
      allow: ['no-unused-vars'],
      deny: ['no-console'],
      warn: ['eqeqeq']
    })
  ]
}