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: @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 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 : 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 Weekly Installs489Repositoryoxc-project/oxcGitHub Stars20.1KFirst Seen12 days agoSecurity AuditsGen Agent Trust HubPassSocketPassSnykWarnInstalled onopencode484codex483cursor482github-copilot482gemini-cli481amp481