Oxc

ESLint에서 마이그레이션 ​

이 가이드는 현재 ESLint를 쓰는 JavaScript·TypeScript 프로젝트가 Oxlint로 옮기려 할 때를 위한 것입니다.

개요 ​

Oxlint와 ESLint는 설정 개념은 비슷하지만, 지원 규칙과 설정 형식은 다릅니다.

Oxlint는 ESLint 코어와 여러 인기 플러그인에서 700개 이상의 규칙을 이미 지원합니다. ESLint 코어 규칙의 거의 전부 지원을 목표로 하며 작업은 진행 중입니다. 프레임워크·파일 형식 지원은 호환성 표로 확인하세요.

마이그레이션할 때 예상할 점:

  • ESLint 코어·인기 플러그인 규칙 대부분 지원
  • 아직 없는 규칙이 있을 수 있음
  • ESLint 설정 파일은 Oxlint 형식으로 변환해야 함
  • Oxlint는 점진 도입을 전제로 설계되었으며, 처음부터 완전 전환이 필수는 아님
  • 네이티브에 없는 ESLint 플러그인은 JS 플러그인으로 사용 가능

Skills로 마이그레이션 ​

migrate-oxlint 스킬로 대화형 마이그레이션을 할 수 있습니다.

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

설치 후 /migrate-oxlint를 실행하면 에이전트가 전체 마이그레이션을 안내합니다.

ESLint flat config에서 마이그레이션 ​

ESLint v9/v10 flat config(eslint.config.js 또는 eslint.config.mjs 등)를 쓰는 경우 @oxlint/migrate로 자동 마이그레이션할 수 있습니다.

마이그레이션 도구 실행 ​

프로젝트 루트에서:

bash
npx @oxlint/migrate <optional-eslint-flat-config-path>

이 명령은:

  • ESLint flat 설정을 읽음
  • 지원되는 규칙을 Oxlint 설정으로 변환
  • 규칙 심각도·옵션 유지
  • 파일·경로별 override를 유지해 저장소 구역마다 다른 규칙 집합 허용
  • globals(예: ...globals.browser)를 같은 의미의 env·globals로 변환
  • 루트 ignore 패턴을 경로 무시로 유지

생성된 .oxlintrc.json은 마이그레이션 후 수동으로 편집할 수 있습니다.

.eslintignore는 Oxlint가 존중하므로 마이그레이션 중 그대로 둬도 되지만, 이후에는 .oxlintrc.json의 "ignorePatterns"로 옮기는 것을 권장합니다. .gitignore로 무시된 경로도 Oxlint가 자동으로 반영합니다.

사용 가능한 옵션 목록을 참고하세요.

타입 인지 TypeScript 규칙 ​

typescript-eslint의 타입 인지 규칙을 쓰는 경우 --type-aware 플래그를 주세요.

bash
npx @oxlint/migrate --type-aware

생성된 Oxlint 설정에 타입 인지 규칙이 포함됩니다.

타입 인지 린팅에는 oxlint-tsgolint가 필요하며, TypeScript 네이티브 재작성(TypeScript 7)을 사용합니다. 대부분의 TypeScript 프로젝트에서 큰 업그레이드 없이 도입할 수 있습니다.

Oxlint의 타입 인지 지원은 타입 인지 린팅을 보세요.

JavaScript 플러그인 ​

Oxlint가 네이티브로 지원하지 않는 플러그인은 JavaScript 플러그인으로 유지할 수 있습니다. @oxlint/migrate가 기본적으로 이런 플러그인도 마이그레이션합니다.

네이티브 규칙·플러그인과 함께 Oxlint에서 그 규칙을 계속 쓸 수 있습니다. JS 플러그인이 모든 ESLint 플러그인을 지원하는 것은 아니지만, ESLint v9 API 대부분을 다루며 계속 개선 중입니다. JavaScript·TypeScript 코드를 다루는 대부분의 ESLint 플러그인은 Oxlint에서 문제 없이 동작해야 합니다.

ESLint 플러그인을 JS 플러그인으로 옮기고 싶지 않으면 --js-plugins=false를 주세요.

자세한 내용은 JS 플러그인을 보세요.

로컬 커스텀 ESLint 플러그인 ​

저장소 내부의 로컬 커스텀 플러그인(예: import pluginMyCompany from './eslint-plugin-my-company/lib/index.js')은 현재 @oxlint/migrate가 자동으로 옮기지 않습니다.

마이그레이션 스크립트 실행 후 Oxlint 설정에 수동으로 추가할 수 있습니다.

json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "jsPlugins": ["./eslint-plugin-company/lib/index.js"]
}
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를 쓰는 것을 권장합니다.

예:

bash
oxlint && eslint

ESLint에서 겹치는 규칙 끄기 ​

eslint-plugin-oxlint로 Oxlint가 이미 처리하는 ESLint 규칙을 끌 수 있습니다.

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

중복 진단이 줄고 린트 시간이 단축될 수 있으며, ESLint는 Oxlint가 아직 지원하지 않는 규칙에만 집중할 수 있습니다.

중요한 규칙이 Oxlint에 더해지면, 설정을 단순화하고 의존성을 줄이기 위해 Oxlint만 쓰는 것을 강력히 권장합니다.

레거시 ESLint(v8.x) 설정에서 마이그레이션 ​

ESLint v8.x 레거시 설정(.eslintrc.js, .eslintrc.json 등)은 @oxlint/migrate로 자동 변환되지 않습니다.

경우에 따라 먼저 @eslint/migrate-config로 ESLint flat config로 자동 변환한 뒤, @oxlint/migrate로 Oxlint로 옮길 수 있습니다.

레거시 v8 설정 형태는 Oxlint 설정과 비슷해, 단순한 구성은 규칙·옵션을 거의 직접 옮길 수 있습니다.

규칙·플러그인 지원 ​

ESLint에서 꼭 쓰는 규칙이 아직 Oxlint에 없을 수 있습니다.

지원 플러그인의 규칙은 거의 모두 포팅될 예정이며 많은 부분은 이미 포팅되었습니다. 포팅되지 않는 경우 일부는 원본 플러그인에서 폐지되었거나 동등한 규칙이 이미 있을 수 있습니다.

메타 이슈에서 규칙·플러그인 구현 상태를 확인할 수 있습니다.

Oxlint에 네이티브로 없는 플러그인은 JS 플러그인 사용을 권장합니다.

© 2026 VoidZero Inc. and Oxc contributors.