How to Gradually Migrate from ESLint to Oxlint (Without Breaking Everything)

简体中文 | English

Intro

Last year (August 22, 2025), Oxlint shipped a new release with type-aware linting support, along with a handy migration tool that can automatically convert your ESLint config to Oxlint.

If you've been dealing with ESLint's sluggish performance and cryptic error messages, now is a great time to make the switch to Oxlint.

This guide will walk you through migrating from ESLint to Oxlint step by step. You can either drop ESLint entirely or run both side by side — the latter being the officially recommended approach for incremental migration.

What is type-aware linting? When type-aware mode is enabled, Oxlint analyzes your code using TypeScript's type information rather than relying solely on static JavaScript syntax rules.

Why Oxlint Is Worth the Switch

• Blazing fast performance — Oxlint is written in Rust.
  • In my own benchmarks, linting my theme repo took ESLint 2.5 seconds, while Oxlint finished in just 33ms (without type-aware) or 475ms (with type-aware).
• Way better diagnostics — Unlike ESLint, which only points you to the offending line and the triggered rule, Oxlint gives you a detailed breakdown of what went wrong, where exactly it happened (with color-coded highlights), and how to fix it.

Migration Steps

First, make sure your ESLint setup is already using the Flat Config format (typically eslint.config.js). If you're still on .eslintrc.js or .eslintrc.json, check out this config migration guide to upgrade first.

Install Dependencies

Add oxlint and oxlint-tsgolint (required for type-aware rule support) to your project:

pnpm add -D oxlint@latest oxlint-tsgolint@latest

pnpm add -D oxlint@latest

npm install -D oxlint@latest oxlint-tsgolint@latest

npm install -D oxlint@latest

yarn add -D oxlint@latest oxlint-tsgolint@latest

yarn add -D oxlint@latest

bun add -D oxlint@latest oxlint-tsgolint@latest

bun add -D oxlint@latest

Note: Since Oxlint is a native Rust binary, it doesn't depend on Node.js at all. You can grab a prebuilt binary directly from the releases page, or just run it on the fly:

pnpm dlx oxlint@latest

npx oxlint@latest

yarn dlx oxlint@latest

bunx oxlint@latest

deno run npm:oxlint@latest

Auto-Migrate Your ESLint Config

The Oxlint team provides an official migration tool that converts your ESLint Flat Config into an Oxlint config.

Run:

pnpm dlx @oxlint/migrate --type-aware

Flag breakdown:

• --type-aware — enables TypeScript type-aware linting

For all available options, refer to the official README.

pnpm dlx @oxlint/migrate

npx @oxlint/migrate --type-aware

npx @oxlint/migrate

yarn dlx @oxlint/migrate --type-aware

yarn dlx @oxlint/migrate

bunx @oxlint/migrate

deno run npm:@oxlint/migrate

Once the tool runs, it'll generate an .oxlint.json config file in your project root and map as many ESLint rules to their Oxlint equivalents as possible.

If you don't see any unsupported rule warnings during migration, that means all your ESLint rules are covered — and you're pretty much clear to remove ESLint entirely.

If you see unsupported rule, but in development, you can try enabling the Nursery ruleset (rules that are actively being developed). Just append --with-nursery to your migration command:

pnpm dlx @oxlint/migrate --type-aware --with-nursery

Advanced: Auto-Track Newly Supported Rules

Auto-track Oxlint's growing support for ESLint rules

Remove ESLint (Optional)

If the previous step produced no unsupported rule warnings — meaning Oxlint fully covers your ESLint ruleset — you can go ahead and remove ESLint:

# Uninstall ESLint and related packages
pnpm remove eslint @eslint/js typescript-eslint
# Remove any ESLint plugins you had installed
pnpm remove eslint-plugin-xxx eslint-config-xxx ...

Then delete eslint.config.js and any remaining .eslintrc.* files.

Update Your package.json Scripts

Full Migration to Oxlint

Refer to the Oxlint CLI docs to replace your ESLint commands with Oxlint equivalents. For example:

{
  "scripts": {
    "lint": "eslint --fix ./src"
  }
}

becomes:

{
  "scripts": {
    "lint": "oxlint --type-aware --fix ./src"
  }
}

Update your lint-staged config as well:

{
  "lint-staged": {
    "**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue,astro,svelte}": "oxlint"
  }
}

Running Oxlint Alongside ESLint (Incremental Migration)

If you'd rather not migrate everything at once, you can run both linters together:

{
  "scripts": {
    "lint": "oxlint --type-aware --fix ./src && eslint --fix ./src"
  }
}

This way, Oxlint handles the bulk of your rules with fast feedback and detailed diagnostics, while ESLint picks up whatever Oxlint doesn't support yet.

Next, install eslint-plugin-oxlint to disable rules in ESLint that Oxlint already covers — no point running the same checks twice:

pnpm add -D eslint-plugin-oxlint@latest

npm install -D eslint-plugin-oxlint@latest

yarn add -D eslint-plugin-oxlint@latest

bun add -D eslint-plugin-oxlint@latest

Then wire it up in eslint.config.js:

import oxlint from 'eslint-plugin-oxlint';

export default [
  // ... your other plugins
  ...oxlint.buildFromOxlintConfigFile('./.oxlintrc.json'), // oxlint should be the last plugin
];

Miscellaneous

If you're using inline comments to suppress specific lint warnings, Oxlint supports that too. Check the docs for details on how to configure inline rule suppression.

Wrapping Up

Drop a comment below if you have any questions or run into issues. Happy linting! 🚀