ESLint에서 마이그레이션하기

이 가이드는 현재 ESLint를 사용 중인 기존 자바스크립트 및 타입스크립트 프로젝트가 Oxlint으로 마이그레이션하는 데 도움을 줍니다.

개요

Oxlint과 ESLint는 유사한 구성 개념을 공유하지만, 지원되는 규칙과 구성 형식에서 다릅니다.

Oxlint은 이미 ESLint 핵심 및 다양한 인기 플러그인의 600개 이상의 규칙을 지원합니다. 우리는 거의 모든 기존의 ESLint 핵심 규칙을 지원할 계획이며, 이 작업은 계속 진행 중입니다.

마이그레이션 시 다음 사항을 기대하시기 바랍니다:

• 대부분의 ESLint 핵심 규칙과 인기 있는 플러그인 규칙이 지원됨
• 일부 규칙은 아직 이용 가능하지 않을 수 있음
• ESLint 구성 파일은 반드시 Oxlint의 구성 형식으로 변환되어야 함
• Oxlint은 점진적 채택을 위한 설계되어 있으며, 초기에 전체 마이그레이션이 필요하지 않음
• Oxlint의 자바스크립트 플러그인을 통해, Oxlint이 내부적으로 구현하지 않은 ESLint 플러그인도 사용할 수 있음

ESLint 평탄 구성에서 마이그레이션하기

프로젝트가 ESLint v9/v10의 평탄 구성(예: eslint.config.js 또는 eslint.config.mjs)을 사용하는 경우, @oxlint/migrate를 사용하여 자동으로 마이그레이션할 수 있습니다.

마이그레이션 도구 실행하기

프로젝트 루트에서:

npx @oxlint/migrate <선택적-eslint-평탄-구성-경로>

이 명령어는 다음과 같은 작업을 수행합니다:

• 당신의 ESLint 평탄 구성 파일을 읽음
• 지원되는 규칙들을 Oxlint 구성으로 변환함
• 규칙의 심각도와 옵션을 유지함
• 파일 및 경로별 오버라이드를 유지하여 리포지토리의 다른 부분에 대해 서로 다른 규칙 세트를 허용함
• globals (예: ...globals.browser)를 해당하는 env 및 globals 값으로 변환함
• 특정 경로/파일을 무시하기 위한 루트 ignore 패턴을 유지함

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

.eslintignore 파일은 Oxlint에서도 인정되며, 마이그레이션 중에도 그대로 두어도 됩니다. 그러나 마이그레이션 후 .oxlintrc.json의 "ignorePatterns" 필드로 내용을 이동하는 것을 권장합니다. 리포지토리의 .gitignore 파일을 통해 무시된 파일/경로도 Oxlint에서 자동으로 인식됩니다.

자세한 내용은 사용 가능한 옵션 목록을 참조하세요.

타입 인식 타입스크립트 규칙

ESLint 설정이 typescript-eslint와 타입 인식 규칙을 사용하는 경우, --type-aware 플래그를 전달할 수 있습니다:

npx @oxlint/migrate --type-aware

이 플래그는 생성된 Oxlint 구성에 타입 인식 규칙이 포함되도록 보장합니다.

참고로 타입 인식 린팅은 oxlint-tsgolint를 필요로 하며, 타입스크립트 내부 재작성(또는 타입스크립트 7) 기반입니다. 그러나 대부분의 타입스크립트 프로젝트에서는 업그레이드 작업 없이도 도입이 가능합니다.

Oxlint의 타입 인식 지원에 대한 추가 정보는 타입 인식 린팅 페이지를 참고하세요.

자바스크립트 플러그인

ESLint 구성이 Oxlint에서 직접 지원되지 않는 플러그인을 사용하는 경우, 자바스크립트 플러그인을 사용하여 이를 유지할 수 있습니다. @oxlint/migrate는 기본적으로 이러한 플러그인을 마이그레이션합니다.

이를 통해 자체 규칙들과 함께 원본 규칙/플러그인을 계속해서 Oxlint에서 사용할 수 있습니다. 자바스크립트 플러그인 기능은 모든 ESLint 플러그인을 지원하지는 않지만, Oxlint의 자바스크립트 플러그인 시스템은 대부분의 ESLint v9 API를 커버하며 지속적으로 개선되고 있습니다. 대부분의 자바스크립트/타입스크립트 코드를 다루는 ESLint 플러그인은 문제 없이 Oxlint에서 작동합니다.

다만, ESLint 플러그인을 자바스크립트 플러그인으로 마이그레이션하고 싶지 않은 경우, --js-plugins=false 플래그를 전달할 수 있습니다.

자바스크립트 플러그인에 대한 자세한 정보는 자바스크립트 플러그인 페이지를 참조하세요.

로컬 사용자 정의 ESLint 플러그인

자신의 리포지토리 내에서 로컬 사용자 정의 ESLint 플러그인을 사용하는 경우(예: import pluginMyCompany from './eslint-plugin-my-company/lib/index.js'), 지금은 @oxlint/migrate가 자동으로 마이그레이션하지 않습니다.

그러나 마이그레이션 스크립트를 실행한 후 수동으로 .oxlintrc.json에 추가할 수 있습니다:

.oxlintrc.json

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

Oxlint과 ESLint 함께 실행하기

필요한 규칙 중 일부가 아직 Oxlint에 존재하지 않는 경우, Oxlint과 ESLint를 동시에 실행할 수 있습니다.

일반적인 설정은 다음과 같습니다:

1. 모든 지원되는 규칙에 대해 Oxlint 활성화
2. 지원되지 않는 규칙은 여전히 ESLint 유지
3. 중복되는 규칙은 ESLint에서 비활성화

왜냐하면 Oxlint은 ESLint보다 훨씬 빠르기 때문에, 먼저 오류를 조기에 잡기 위해 먼저 Oxlint을 실행하고, 필요한 경우에만 ESLint로 넘어가는 것이 좋습니다.

예시:

oxlint && eslint

ESLint에서 중복 규칙 비활성화하기

eslint-plugin-oxlint를 사용하여 이미 Oxlint이 처리하는 규칙을 비활성화할 수 있습니다:

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

이 방법은 중복 진단을 줄이고, 린팅 시간을 크게 단축시키며, ESLint가 아직 지원하지 않는 규칙들에만 집중하도록 돕습니다.

장기적으로 - 나머지 중요한 규칙들이 모두 Oxlint에 추가되면 - 완전히 Oxlint로 전환하는 것이 매우 추천됩니다. 이는 설정을 단순화하고 프로젝트의 종속성 수를 줄일 수 있습니다.

레거시 ESLint(v8.x) 구성에서 마이그레이션하기

프로젝트가 레거시 구성 파일(예: .eslintrc.js 또는 .eslintrc.json)을 사용하는 ESLint v8.x를 사용하는 경우, @oxlint/migrate로 자동 마이그레이션할 수 없습니다.

어떤 경우에는 먼저 @eslint/migrate-config를 사용해 레거시 구성 파일을 자동으로 ESLint 평탄 구성으로 마이그레이션한 후, 그 다음에 @oxlint/migrate로 Oxlint으로 마이그레이션할 수 있습니다.

"레거시" 형태의 ESLint v8.x 구성 파일은 실제로 Oxlint의 구성 형식과 매우 유사하므로, 간단한 설정에서는 대부분의 규칙과 옵션을 직접 번역할 수 있습니다.

규칙/플러그인 지원

특정 규칙을 의존하고 있으나 아직 Oxlint으로 이식되지 않은 경우가 있을 수 있습니다.

우리가 지원하는 플러그인의 거의 모든 규칙은 이식될 예정이며, 대부분은 이미 이식되었습니다. 아직 이식되지 않을 것으로 예상되는 규칙들은 원본 플러그인에서 더 이상 사용되지 않거나, 이미 대체 규칙이 구현된 경우가 많습니다.

필요로 하는 규칙이 구현될 예정인지, 아니면 이미 동등한 규칙에 의해 구현되었는지 확인하려면 메타 이슈를 확인하세요.

Oxlint에서 직접 구현되지 않은 플러그인의 경우, 자바스크립트 플러그인 사용을 권장합니다.