migrate-oxlint

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, and will be used by this skill: @oxlint/migrate

Step 1: Run Automated Migration

Run the migration tool in the project root:

npx @oxlint/migrate

This reads your ESLint flat config (eslint.config.js for example) and generates a .oxlintrc.json file from it. It will find your ESLint config file automatically in most cases.

See options below for more info.

Key Options

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:

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

ESLint core rules are usable in oxlint without needing to configure a plugin in the config file.

Rule Categories

Oxlint groups rules into categories for bulk configuration, though only correctness is enabled by default:

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

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

Individual rule settings in rules override category settings.

@oxlint/migrate will turn correctness off to avoid enabling additional rules that weren't enabled by your ESLint config. You can choose to enable additional categories after migration if desired.

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 not. Some rules may be mentioned in the output from --details as having equivalents in oxlint that were not automatically mapped by the migration tool. In those cases, consider enabling the equivalent oxlint rule manually after migration.

Step 3: Install Oxlint

Install the core oxlint package (use yarn install, pnpm install, vp install, bun install, etc. depending on your package manager):

npm install -D oxlint

If you want to add the oxlint-tsgolint package, if you intend to use type-aware rules that require TypeScript type information:

npm install -D oxlint-tsgolint

No other packages besides the above are needed by default, though you will need to keep/install any additional ESLint plugins that were migrated into jsPlugins. Do not add @oxlint/migrate to the package.json, it is meant for one-off usage.

Step 4: Handle Unsupported Features

Some features require manual attention:

• Local plugins (relative path imports): Must be migrated manually to jsPlugins
• eslint-plugin-prettier: Supported, but very slow. It is recommended to use oxfmt instead, or switch to prettier --check as a separate step alongside oxlint.
• settings in override configs: Oxlint does not support settings inside overrides blocks.
• ESLint v9+ plugins: Not all work with oxlint's JS Plugins API, but the majority will.

Local Plugins

If you have any custom ESLint rules in the project repo itself, you can migrate them manually after running the migration tool by adding them to the jsPlugins field in .oxlintrc.json:

{
  "jsPlugins": ["./path/to/my-plugin.js"],
  "rules": {
    "local-plugin/rule-name": "error"
  }
}

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 5: 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 src/
npx oxlint --fix src/

Common CLI Options

Additional oxlint options:

• --tsconfig <path>: Specify tsconfig.json path, likely unnecessary unless you have a non-standard name for tsconfig.json.

Tips

• You can run alongside ESLint if necessary: Oxlint is designed to complement ESLint during migration, but with JS Plugins many projects can switch over fully without losing many rules.
• Disable comments work: // eslint-disable and // eslint-disable-next-line comments are supported by oxlint. Use --replace-eslint-comments when running @oxlint/migrate to convert them to // oxlint-disable equivalents if desired.
• List available rules: Run npx oxlint --rules to see all supported rules, or refer to the rule documentation.
• Schema support: Add "$schema": "./node_modules/oxlint/configuration_schema.json" to .oxlintrc.json for editor autocompletion if the migration tool didn't do it automatically.
• Output formats: default, stylish, json, github, gitlab, junit, checkstyle, unix
• Ignore files: .eslintignore is supported by oxlint if you have it, but it's recommended to move any ignore patterns into the ignorePatterns field in .oxlintrc.json for consistency and simplicity. All files and paths ignored via a .gitignore file will be ignored by oxlint by default as well.
• If you ran the migration tool multiple times, remove the .oxlintrc.json.bak backup file created by the migration tool once you've finished migrating.
• If you are not using any JS Plugins and have replaced your ESLint configuration, you can remove all ESLint packages from your project dependencies.
• Ensure your editor is configured to use oxlint instead of ESLint for linting and error reporting. You may want to install the Oxc extension for your preferred editor. See https://oxc.rs/docs/guide/usage/linter/editors.html for more details.

References

• CLI Reference
• Config File Reference
• Complete Oxlint rule list and docs