Миграция с ESLint

Руководство для проектов на JavaScript и TypeScript, которые уже используют ESLint и хотят перейти на Oxlint.

Обзор

У Oxlint и ESLint похожие идеи конфигурации, но отличаются поддерживаемые правила и форматы конфигов.

В Oxlint уже более 700 правил из ядра ESLint и популярных плагинов. Планируется поддержка почти всех правил ядра ESLint; работа продолжается. Сверяйтесь с матрицей совместимости.

При миграции ожидайте:

• Большинство правил ядра ESLint и популярных плагинов поддерживаются
• Часть правил может быть ещё недоступна
• Файлы конфигурации ESLint нужно перевести в формат Oxlint
• Oxlint рассчитан на поэтапное внедрение; полный перенос сразу не обязателен
• JS-плагины Oxlint позволяют использовать ESLint-плагины без нативной реализации

Миграция через Skills

Интерактивно можно через skill migrate-oxlint:

npx skills add https://github.com/oxc-project/oxc --skill migrate-oxlint

После установки выполните /migrate-oxlint — агент проведёт по шагам миграции.

Миграция с ESLint flat config

Если у вас flat config ESLint v9/v10 (например eslint.config.js или eslint.config.mjs), автоматическая миграция — через @oxlint/migrate.

Запуск утилиты

Из корня проекта:

npx @oxlint/migrate <опционально-путь-к-flat-config-eslint>

Утилита:

• Читает flat config ESLint
• Переносит поддерживаемые правила в конфиг Oxlint
• Сохраняет строгость и опции правил
• Сохраняет переопределения по файлам и путям
• Переводит globals (например ...globals.browser) в env и globals
• Сохраняет корневые шаблоны ignore

Сгенерированный .oxlintrc.json можно править вручную.

Файлы .eslintignore Oxlint учитывает; их можно оставить на время миграции, но рекомендуем перенести содержимое в ignorePatterns в .oxlintrc.json. Пути из .gitignore Oxlint тоже учитывает автоматически.

Список доступных опций.

Правила TypeScript с типами

Если в ESLint используется typescript-eslint с правилами, нуждающимися в типах, передайте --type-aware:

npx @oxlint/migrate --type-aware

Тогда в конфиг Oxlint попадут соответствующие правила.

Нужен пакет oxlint-tsgolint, основанный на нативной переписке TypeScript (TypeScript 7); в большинстве проектов переход без больших апгрейдов возможен.

Подробнее — страница «Линтинг с типами».

JavaScript-плагины

Плагины ESLint без нативной поддержки в Oxlint можно оставить через JS-плагины. @oxlint/migrate по умолчанию переносит и их.

Так вы продолжите использовать эти правила в Oxlint вместе с нативными. JS-плагины не покрывают абсолютно все ESLint-плагины, но API Oxlint близко к ESLint v9 и развивается; большинство плагинов для JS/TS должны работать.

Чтобы не мигрировать ESLint-плагины в JS-плагины, укажите --js-plugins=false.

Подробнее — страница JS-плагинов.

Локальные кастомные плагины ESLint

Локальные плагины из репозитория (например import pluginMyCompany from './eslint-plugin-my-company/lib/index.js') @oxlint/migrate пока не переносит автоматически.

Их можно добавить в конфиг Oxlint вручную после миграции:

.oxlintrc.json

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

oxlint.config.ts

import { defineConfig } from "oxlint";

export default defineConfig({
  jsPlugins: ["./eslint-plugin-company/lib/index.js"],
});

Одновременный запуск Oxlint и ESLint

Если не все нужные правила есть в Oxlint, можно запускать оба линтера.

Типичная схема:

1. Включить Oxlint для поддерживаемых правил
2. Оставить ESLint для остального
3. Отключить в ESLint пересекающиеся правила

Oxlint намного быстрее ESLint — разумно сначала запускать его, а ESLint — при необходимости.

Пример:

oxlint && eslint

Отключение дублей в ESLint

Можно использовать eslint-plugin-oxlint, чтобы отключить в ESLint правила, которые уже покрывает Oxlint:

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

Меньше дублирующих диагностик, короче время линта, ESLint фокусируется на непокрытом.

В перспективе, когда важные правила появятся в Oxlint, лучше полностью перейти на Oxlint и упростить зависимости.

Миграция с legacy ESLint (v8.x)

Конфиги v8 (.eslintrc.js, .eslintrc.json и т.п.) @oxlint/migrate не обрабатывает напрямую.

Иногда помогает сначала автоматически перевести их в flat config через @eslint/migrate-config, затем — @oxlint/migrate.

Форма legacy v8 близка к конфигу Oxlint: в простых случаях правила и опции переносятся напрямую.

Поддержка правил и плагинов

Отдельные нужные вам правила ESLint могут ещё не быть портированы.

Почти все правила поддерживаемых плагинов планируется перенести — большая часть уже есть. Часть в оригинальных плагинах устарела или заменена эквивалентами.

Статус — в meta issue.

Для плагинов без нативной реализации в Oxlint рекомендуем JS-плагины.