unplugin-oxlint

library0.8.0jsnpmunverified

unplugin-oxlint is a universal bundler plugin designed to integrate the high-performance Oxlint linter into various JavaScript and TypeScript projects. Currently at version 0.8.0, this library maintains an active release cadence, frequently updating to support the latest Oxlint versions and bundler ecosystems. Its core differentiator is the ability to seamlessly embed Oxlint across popular build tools like Vite, Rollup, esbuild, and Webpack through the `unplugin` ecosystem. It also provides a Node.js API for programmatic linting. Key features include highly optimized performance by linting only changed files via `chokidar`, user-friendly terminal output, and optional integration with ESLint setups using `eslint-plugin-oxlint` to disable redundant rules. This allows for flexible adoption, either replacing ESLint or running alongside it for a faster feedback loop.

testing

npm install unplugin-oxlint

github ↗package ↗

INSTALL

IMPORT

SIG · UNPLUGIN-OXLINT

unplugin-oxlint

testingjavascriptv0.8.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Oxlint

✓ import Oxlint from 'unplugin-oxlint/vite'

✗ import Oxlint from 'unplugin-oxlint'

Bundler-specific plugins are imported from subpaths (e.g., '/vite', '/rollup', '/esbuild', '/webpack'). The main 'unplugin-oxlint' export is for the Node.js API.

lint

✓ import { lint } from 'unplugin-oxlint'

✗ const { lint } = require('unplugin-oxlint')

The Node.js API `lint` function is an ESM named export. While CommonJS `require` might technically work in some setups, ESM import is the intended and recommended pattern, especially for TypeScript users.

Oxlint (Webpack/esbuild CJS)

✓ const Oxlint = require('unplugin-oxlint/webpack')

✗ import Oxlint from 'unplugin-oxlint/webpack'

For CommonJS-based bundler configurations (like older Webpack or esbuild plugins), `require` with the specific subpath is necessary. ESM `import` will lead to errors in these contexts.

Plugin (TypeScript Type)

✓ import type { UnpluginFactory } from 'unplugin'

The underlying `unplugin` library provides generic types for plugin factories. While not directly from `unplugin-oxlint`, understanding `unplugin` types is useful for advanced usage or custom integrations.

This Vite configuration demonstrates how to integrate `unplugin-oxlint` with basic options, including glob patterns, conditional auto-fixing via an environment variable, and setting the current working directory for linting.

import { defineConfig } from 'vite'; import Oxlint from 'unplugin-oxlint/vite'; import path from 'path'; import { fileURLToPath } from 'url'; const __dirname = path.dirname(fileURLToPath(import.meta.url)); export default defineConfig({ plugins: [ Oxlint({ includes: ['src/**/*.ts', 'src/**/*.js', 'src/**/*.vue'], excludes: ['node_modules/', 'dist/'], glob: true, // Enable glob patterns for includes/excludes fix: process.env.LINT_FIX === 'true', // Optional: enable auto-fixing via environment variable cwd: path.resolve(__dirname, './'), // Set current working directory for oxlint quiet: process.env.CI === 'true', // Only report errors in CI environments }), ], build: { // Ensure build is clean, useful for CI emptyOutDir: true, }, resolve: { alias: { '@': path.resolve(__dirname, './src'), }, }, }); console.log(`Oxlint plugin enabled for environment: ${process.env.NODE_ENV}`); // To run this: // 1. Install deps: `npm i -D vite unplugin-oxlint oxlint` // 2. Add to package.json scripts: `"lint:fix": "LINT_FIX=true vite build"` // 3. Run `npm run dev` or `npm run build` for linting. `npm run lint:fix` to fix.

Debug

Known issues

breakingThe `unox` command-line utility was removed in v0.7.0. Users must now exclusively use the bundler plugin or the Node.js API for linting.

fix

Migrate from using the `unox` command to either configuring `unplugin-oxlint` as a bundler plugin (e.g., in `vite.config.ts`) or calling the `lint` function directly from a Node.js script.

affects: >=0.7.0

deprecatedThe `options.path` configuration property has been deprecated. It is recommended to use `options.includes` for specifying files or directories to be linted.

fix

Replace `options.path` with `options.includes`. For glob patterns, ensure `options.glob: true` is also set. Example: `Oxlint({ includes: ['src/**/*.ts'], glob: true })`.

affects: >=0.7.0

gotcha`oxlint` is a peer dependency and must be installed separately alongside `unplugin-oxlint`. Failure to do so will result in runtime errors.

fix

Ensure `oxlint` is installed as a development dependency in your project: `npm i -D oxlint` or `pnpm add -D oxlint`. Check the `unplugin-oxlint` peer dependency range for compatible `oxlint` versions.

affects: >=0.1.0

gotchaWhen migrating from ESLint, `eslint-plugin-oxlint` can be used to disable overlapping ESLint rules to prevent duplicate reporting and improve performance. Without it, you might get warnings/errors from both linters for the same issue.

fix

Install `eslint-plugin-oxlint` (`npm i -D eslint-plugin-oxlint`) and configure your ESLint setup (e.g., `eslint.config.js`) to extend `oxlint.configs['flat/all']` or specific configurations to disable redundant rules.

affects: >=0.1.0

gotchaThe `unplugin-oxlint` package uses bundler-specific entry points (e.g., `unplugin-oxlint/vite`, `unplugin-oxlint/rollup`). Directly importing from `unplugin-oxlint` will yield the Node.js API, not the bundler plugin.

fix

Always use the specific bundler subpath for plugin imports, e.g., `import Oxlint from 'unplugin-oxlint/vite'` for Vite, or `require('unplugin-oxlint/webpack')` for Webpack.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'oxlint'

The `oxlint` package, a peer dependency, is not installed.

fix

Run `npm install oxlint --save-dev` (or `pnpm add -D oxlint`, `yarn add -D oxlint`) in your project root.

TypeError: (0 , unplugin_oxlint_vite__WEBPACK_IMPORTED_MODULE_0__.default) is not a function

Attempting to use `unplugin-oxlint`'s bundler integration without calling it as a function (e.g., `Oxlint` instead of `Oxlint()`).

fix

Ensure the imported `Oxlint` plugin is always called as a function, typically with no arguments or an options object, e.g., `plugins: [Oxlint()]`.

Error: `plugins` option must be an array, but got undefined

The `plugins` array in the bundler config (e.g., `vite.config.ts`) is missing or incorrectly structured, causing `unplugin-oxlint` not to be registered properly.

fix

Verify that `Oxlint()` is correctly placed within the `plugins` array in your bundler configuration file, e.g., `plugins: [Oxlint({ /* options */ })]`.

Module not found: Can't resolve 'unplugin-oxlint/esbuild' in '...'

Incorrect import path for the specific bundler integration, or a CommonJS module trying to use an ESM import, or vice-versa.

fix

Double-check the import statement. For esbuild and webpack, use `require('unplugin-oxlint/esbuild')()` or `require('unplugin-oxlint/webpack')()` respectively. For Vite/Rollup, use `import Oxlint from 'unplugin-oxlint/vite'`.

Upgrade

Version history

0.8.0latest on npm

Audit

Dependencies

oxlintrequiredCore linter that unplugin-oxlint integrates. It's a peer dependency, meaning users must install it separately.

Agent activity

15 hits · last 30 days

node

Bingbot

Resources

githubhttps://github.com/tmg0/unplugin-oxlint ↗

packagehttps://www.npmjs.com/package/unplugin-oxlint ↗