migrate-oxlint

このスキルは、JavaScript/TypeScript プロジェクトを ESLint から Oxlint へマイグレーションするプロセスをガイドします。

概要

Oxlint は高性能なリンターであり、多くの人気 ESLint ルールを Rust でネイティブに実装しています。ESLint と並行して使用することも、完全な置き換えとしても使用できます。

公式マイグレーションツールが利用可能であり、このスキルで使用されます: @oxlint/migrate

ステップ 1: 自動マイグレーションの実行

プロジェクトルートでマイグレーションツールを実行してください:

npx @oxlint/migrate

これにより ESLint フラットコンフィグ (例: eslint.config.js) が読み込まれ、.oxlintrc.json ファイルが生成されます。ほとんどの場合、ESLint コンフィグファイルは自動的に検出されます。

詳細については以下のオプションを参照してください。

キーオプション

オプション	説明
--type-aware	@typescript-eslint からのタイプ対応ルールを含める (マイグレーション後に oxlint-tsgolint パッケージのインストールが必要)
--with-nursery	開発中の実験的ルールを含める。ESLint 相当物と完全に安定または一致していない場合がある
--js-plugins [bool]	jsPlugins 経由の ESLint プラグインマイグレーションの有効/無効化 (デフォルト: 有効)
--details	マイグレーションできなかったルールを列挙する
--replace-eslint-comments	すべての // eslint-disable コメントを // oxlint-disable に変換する
--output-file <file>	別の出力パスを指定 (デフォルト: .oxlintrc.json)

ESLint コンフィグがデフォルトの場所にない場合は、パスを明示的に渡してください:

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

ステップ 2: 生成されたコンフィグをレビュー

マイグレーション後、生成された .oxlintrc.json をレビューしてください。

プラグインマッピング

マイグレーションツールは ESLint プラグインを oxlint の組み込み相当物に自動的にマッピングします。以下のテーブルは生成されたコンフィグをレビューする際の参考用です:

ESLint プラグイン	Oxlint プラグイン名
@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 / eslint-plugin-jsx-a11y-x	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

デフォルトプラグイン (plugins フィールドが省略されている場合に有効): unicorn, typescript, oxc。 plugins 配列を明示的に設定すると、これらのデフォルトがオーバーライドされます。

ESLint コアルールはコンフィグファイルでプラグインを設定する必要なく oxlint で使用できます。

ルールカテゴリ

Oxlint はルールを一括設定用のカテゴリにグループ化していますが、デフォルトでは correctness のみが有効です:

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

利用可能なカテゴリ: correctness (デフォルト: 有効), suspicious, pedantic, perf, style, restriction, nursery。

rules 内の個別ルール設定はカテゴリ設定をオーバーライドします。

@oxlint/migrate は ESLint コンフィグで有効になっていなかった追加ルールが有効になるのを避けるため、correctness をオフにします。マイグレーション後に必要に応じて追加カテゴリを有効にすることができます。

マイグレーションされなかったルールを確認

--details で実行して、どの ESLint ルールがマイグレーションできなかったかを確認してください:

npx @oxlint/migrate --details

出力をレビューして、これらのルール用に ESLint を保つかどうかを決定してください。--details からの出力には、oxlint に同等物があるとして言及されているが、マイグレーションツールによって自動的にマッピングされなかったルールもあります。このような場合は、マイグレーション後に同等の oxlint ルールを手動で有効にすることを検討してください。

ステップ 3: Oxlint のインストール

コアの oxlint パッケージをインストールしてください (パッケージマネージャーに応じて yarn install, pnpm install, vp install, bun install など を使用):

npm install -D oxlint

TypeScript 型情報を必要とするタイプ対応ルールを使用したい場合は、oxlint-tsgolint パッケージを追加したい場合:

npm install -D oxlint-tsgolint

デフォルトでは上記のパッケージのみが必要ですが、jsPlugins にマイグレーションされた追加の ESLint プラグインを保つ/インストールする必要があります。@oxlint/migrate を package.json に追加しないでください。これはワンオフの使用を想定しています。

ステップ 4: サポートされていない機能を処理

いくつかの機能は手動での対応が必要です:

• ローカルプラグイン (相対パスインポート): jsPlugins に手動でマイグレーションする必要があります
• eslint-plugin-prettier: サポートされていますが、非常に遅いです。代わりに oxfmt を使用するか、prettier --check を oxlint と並行して別のステップとして切り替えることをお勧めします。
• オーバーライドコンフィグ内の settings: Oxlint は overrides ブロック内の settings をサポートしていません。
• ESLint v9+ プラグイン: すべてが oxlint の JS Plugins API で機能するわけではありませんが、大多数は機能します。

ローカルプラグイン

プロジェクトリポジトリ内に独自の ESLint ルールがある場合は、マイグレーションツールの実行後に .oxlintrc.json の jsPlugins フィールドに追加することで手動でマイグレーションできます:

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

外部 ESLint プラグイン

組み込み oxlint 相当物がない ESLint プラグインの場合は、jsPlugins フィールドを使用して読み込んでください:

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

ステップ 5: CI とスクリプトを更新

ESLint コマンドを oxlint に置き換えてください。パス引数はオプションです。oxlint はデフォルトで現在の作業ディレクトリをリントします。

# 前
npx eslint src/
npx eslint --fix src/

# 後
npx oxlint src/
npx oxlint --fix src/

一般的な CLI オプション

ESLint	oxlint 相当物
eslint .	oxlint (デフォルト: cwd をリント)
eslint src/	oxlint src/
eslint --fix	oxlint --fix
eslint --max-warnings 0	oxlint --deny-warnings または --max-warnings 0
eslint --format json	oxlint --format json

oxlint の追加オプション:

• --tsconfig <path>: tsconfig.json パスを指定。tsconfig.json に非標準的な名前がある場合以外は不要である可能性があります。

ヒント

• 必要に応じて ESLint と並行して実行できます: Oxlint はマイグレーション中に ESLint を補完するように設計されていますが、JS Plugins を使用すれば多くのプロジェクトは多くのルールを失うことなく完全に切り替えることができます。
• 無効化コメントが機能します: // eslint-disable と // eslint-disable-next-line コメントは oxlint でサポートされています。必要に応じて @oxlint/migrate を実行する際に --replace-eslint-comments を使用して、// oxlint-disable 相当物に変換してください。
• 利用可能なルールをリスト表示: npx oxlint --rules を実行してサポートされているすべてのルールを確認するか、ルールドキュメントを参照してください。
• スキーマサポート: マイグレーションツールが自動的に行わなかった場合は、.oxlintrc.json に "$schema": "./node_modules/oxlint/configuration_schema.json" を追加してエディタの自動補完を有効にしてください。
• 出力フォーマット: default, stylish, json, github, gitlab, junit, checkstyle, unix
• ファイルを無視: .eslintignore は oxlint でサポートされていますが、一貫性と単純性のために、すべての無視パターンを .oxlintrc.json の ignorePatterns フィールドに移動することをお勧めします。.gitignore ファイル経由で無視されるすべてのファイルとパスは、デフォルトで oxlint でも無視されます。
• マイグレーションツールを複数回実行した場合は、マイグレーションを完了したら、マイグレーションツールで作成された .oxlintrc.json.bak バックアップファイルを削除してください。
• JS Plugins を使用していなく、ESLint コンフィグを置き換えた場合は、プロジェクト依存関係からすべての ESLint パッケージを削除できます。
• エディタが ESLint ではなく oxlint をリントとエラー報告に使用するように設定されていることを確認してください。推奨エディタ用の Oxc 拡張機能をインストールすることをお勧めします。詳細は https://oxc.rs/docs/guide/usage/linter/editors.html を参照してください。

参考資料

• CLI リファレンス
• コンフィグファイルリファレンス
• 完全な Oxlint ルールリストとドキュメント