This skill guides you through migrating a JavaScript/TypeScript project from ESLint to Oxlint.

Overview

Oxlint is a high-performance linter that implements many popular ESLint rules natively in Rust. It can be used alongside ESLint or as a full replacement.

An official migration tool is available: @oxlint/migrate

Step 1: Run Automated Migration

Run the migration tool in the project root:

npx @oxlint/migrate

This reads your ESLint flat config and generates a .oxlintrc.json file.

Key Options

Option Description

--merge

Merge with an existing .oxlintrc.json instead of overwriting

--type-aware

Include type-aware rules (requires running oxlint with --type-aware )

--with-nursery

Include experimental rules still under development

--js-plugins [bool]

Enable/disable ESLint plugin migration via jsPlugins (default: enabled)

--details

List rules that could not be migrated

--replace-eslint-comments

Convert // eslint-disable comments to // oxlint-disable

--output-file <file>

Specify output path (default: .oxlintrc.json )

If your ESLint config is not at the default location, pass the path explicitly:

npx @oxlint/migrate ./path/to/eslint.config.js

Step 2: Review Generated Config

After migration, review the generated .oxlintrc.json .

Plugin Mapping

The migration tool automatically maps ESLint plugins to oxlint's built-in equivalents. The following table is for reference when reviewing the generated config:

ESLint Plugin Oxlint Plugin Name

@typescript-eslint/eslint-plugin

typescript

eslint-plugin-react / eslint-plugin-react-hooks

react

eslint-plugin-import / eslint-plugin-import-x

import

eslint-plugin-unicorn

unicorn

eslint-plugin-jsx-a11y

jsx-a11y

eslint-plugin-react-perf

react-perf

eslint-plugin-promise

promise

eslint-plugin-jest

jest

@vitest/eslint-plugin

vitest

eslint-plugin-jsdoc

jsdoc

eslint-plugin-next

nextjs

eslint-plugin-node

node

eslint-plugin-vue

vue

Default plugins (enabled when plugins field is omitted): unicorn , typescript , oxc . Setting the plugins array explicitly overrides these defaults.

Rule Categories

Oxlint groups rules into categories for bulk configuration:

{ "categories": { "correctness": "warn", "suspicious": "warn" } }

Available categories: correctness (default: enabled), suspicious , pedantic , perf , style , restriction , nursery .

Individual rule settings in rules override category settings.

Check Unmigrated Rules

Run with --details to see which ESLint rules could not be migrated:

npx @oxlint/migrate --details

Review the output and decide whether to keep ESLint for those rules or find oxlint alternatives.

Step 3: Handle Unsupported Features

Some features require manual attention:

• Local plugins (relative path imports): Must be migrated manually to jsPlugins

• eslint-plugin-prettier : Not supported. Use oxfmt instead

• settings in override configs: Oxlint does not support settings inside overrides blocks

• ESLint v9+ plugins: Not all work with oxlint's JS Plugins API. Test with --js-plugins

External ESLint Plugins

For ESLint plugins without a built-in oxlint equivalent, use the jsPlugins field to load them:

{ "jsPlugins": ["eslint-plugin-custom"], "rules": { "custom/my-rule": "warn" } }

Step 4: Update CI and Scripts

Replace ESLint commands with oxlint. Path arguments are optional; oxlint defaults to the current working directory.

Before

npx eslint src/ npx eslint --fix src/

After

npx oxlint@latest npx oxlint@latest --fix

Common CLI Options

ESLint oxlint

eslint .

oxlint (default: cwd)

eslint src/

oxlint src/

eslint --fix

oxlint --fix

eslint --max-warnings 0

oxlint --deny-warnings or --max-warnings 0

eslint --format json

oxlint --format json

eslint -c config.json

oxlint --config config.json

Additional oxlint options:

• --type-aware : Enable rules requiring TypeScript type information

• --tsconfig <path> : Specify tsconfig.json path for type-aware linting

Tips

• Start gradually: Enable correctness rules first (the default), then progressively add suspicious , pedantic , etc.

• Run alongside ESLint: Oxlint is designed to complement ESLint during migration. You can run both until all rules are covered.

• Disable comments work: // eslint-disable and // eslint-disable-next-line comments are supported by oxlint. Use --replace-eslint-comments to convert them to // oxlint-disable if desired.

• List available rules: Run npx oxlint@latest --rules to see all supported rules.

• Schema support: Add "$schema": "./node_modules/oxlint/configuration_schema.json" to .oxlintrc.json for editor autocompletion.

• Output formats: default , stylish , json , github , gitlab , junit , checkstyle , unix

References

• CLI Reference

• Config File Reference