Migrate from ESLint

This guide is for existing JavaScript and TypeScript projects that currently use ESLint and want to migrate to Oxlint.

If you are starting a new project, or do not need to preserve an existing ESLint configuration, we recommend initializing a fresh Oxlint config instead:

oxlint --init

Overview

Oxlint and ESLint share similar configuration concepts, but they differ in supported rules and config formats.

Oxlint already supports more than 600 rules from ESLint core and various popular plugins. We intend to support nearly all existing ESLint core rules, and this work is ongoing.

When migrating, expect the following:

• Most ESLint core rules and popular plugin rules are supported
• Some rules may not yet be available
• ESLint configuration files must be converted to Oxlint’s config format
• Oxlint is designed for incremental adoption; a full migration is not required upfront
• Oxlint's JS Plugins allow usage of ESLint plugins that are not implemented natively by Oxlint

Migrating from an ESLint flat config

If your project uses an ESLint v9/v10 flat config (e.g. eslint.config.js or eslint.config.mjs), you can migrate automatically using @oxlint/migrate.

Run the migration tool

From the project root:

npx @oxlint/migrate <optional-eslint-flat-config-path>

This command:

• Reads your ESLint flat config file
• Converts supported rules to an Oxlint config
• Preserves rule severities and options
• Preserves file and path-specific overrides to allow different rulesets for different parts of a repo
• Converts globals (e.g. ...globals.browser) to equivalent env and globals values
• Preserves root ignore patterns for ignoring specific paths/files

The generated .oxlintrc.json config can be edited manually after migration.

.eslintignore files will be respected by Oxlint and can be left in place during migration, but we recommend moving the contents to the "ignorePatterns" field in .oxlintrc.json after migrating. Files/paths ignored via a repo's .gitignore file will also be respected by Oxlint automatically.

See the list of available options for more details.

Type-Aware TypeScript rules

If your ESLint setup uses typescript-eslint with type-aware rules, you can pass the --type-aware flag:

npx @oxlint/migrate --type-aware

This ensures the generated Oxlint config includes type-aware rules.

Note that type-aware linting is based on the TypeScript native rewrite (aka TypeScript 7), but should be possible to adopt in most TypeScript projects without too much upgrade work.

For further information on Oxlint's type-aware support, see the Type-Aware Linting page.

JavaScript plugins

If your ESLint config uses plugins that are not supported natively by Oxlint, you can retain them using JavaScript plugins.

To migrate ESLint plugins along with the natively-supported plugins, use the --js-plugins flag:

npx @oxlint/migrate --js-plugins

This allows you to continue using those rules via Oxlint alongside the native rules/plugins. The JS Plugins functionality does not support all ESLint plugins, but Oxlint's JavaScript plugin system covers a vast majority of the ESLint v9 API and is actively being improved. Most ESLint plugins covering JavaScript/TypeScript code should work in Oxlint without problems.

For more information on JavaScript Plugins, see the JS Plugins page.

Local custom ESLint plugins

If you use local custom ESLint plugins from within your own repo (e.g. import pluginMyCompany from './eslint-plugin-my-company/lib/index.js'), these will not be migrated automatically by @oxlint/migrate right now.

However, they can be added manually to the .oxlintrc.json after running the migration script:

.oxlintrc.json

{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "jsPlugins": ["./eslint-plugin-company/lib/index.js"],
  "rules": {
    // ...
  },
}

Running Oxlint and ESLint together

If not all required rules are available in Oxlint, you can run Oxlint and ESLint side by side.

A common setup is:

1. Enable Oxlint for all supported rules
2. Keep ESLint for unsupported rules
3. Disable overlapping rules in ESLint

Because Oxlint is significantly faster than ESLint, it is recommended to run Oxlint first to catch errors early, then fall back to ESLint only if needed.

For example:

oxlint && eslint

Disabling overlapping rules in ESLint

You can use eslint-plugin-oxlint to disable ESLint rules that are already handled by Oxlint:

npm install --save-dev oxlint-eslint-plugin

This reduces duplicate diagnostics, can help cut down your linting time considerably, and allows ESLint to focus only on rules that Oxlint does not yet support.

Long-term - once remaining important rules been added in Oxlint - we strongly recommend moving fully to Oxlint to simplify your setup and reduce the number of npm dependencies for your project.

Migrating from legacy ESLint (v8.x) configs

If your project uses legacy ESLint config files (such as .eslintrc.js or .eslintrc.json), they must be migrated manually.

The "legacy" ESLint v8.x configuration file shape maps closely to Oxlint’s config format, so most rules and options can be translated directly.

For simpler legacy configuration files, you may also migrate them to an ESLint flat config first, and then to Oxlint using @oxlint/migrate.

Rule/plugin support

You may have specific rules that you rely on in ESLint that are not yet ported to Oxlint.

Almost all rules from our supported plugins will be ported - and a majority already have been. For those that will not be ported, some rules are deprecated in the original plugins, or have alternatives implemented already.

You can check the meta issue for rule/plugin implementation status to see if the rules you rely on are planned for implementation, or if they have already been implemented by other, equivalent rules.

For plugins that are not implemented natively in Oxlint, it is recommended to use JS Plugins.