5분 만에 Oxlint 시작하기: ESLint보다 50배 빠른 코드 검사 도구 (실전 튜토리얼)

eslint ./src를 실행한 후 터미널에서 스크롤되는 파일 목록을 보며 수십 초 또는 그 이상을 기다린 경험이 있으신가요? 프로젝트가 클수록 대기 시간은 길어지고, 개발 리듬이 심각하게 느려집니다.

오늘은 이런 경험을 완전히 바꿀 수 있는 도구, Oxlint를 소개합니다. ESLint보다 50배 이상 빠를 뿐만 아니라, 바로 사용할 수 있어 학습 비용이 거의 없습니다.

코드 검사란 무엇인가요?

Oxlint를 깊이 이해하기 전에, 먼저 “코드 검사”(Linting)가 무엇인지 이해해 봅시다.

왜 Linter가 필요한가요?

코드 검사 도구는 코드의 문제를 발견해 줍니다:

// 이런 문제들은 한눈에 알아채기 어려울 수 있습니다
const name = 'test';
function getName() {
  return nam; // 철자 오류! name이어야 합니다
}

if (x = 10) { // = 대신 === 여야 합니다
  console.log('x is 10');
}

var unused = 'I am never used'; // 정의했지만 사용하지 않음

코드 검사 도구는 다음을 도와줍니다:

• 오류 발견: 철자 오류, 구문 문제, 논리 함정
• 스타일 통일: 팀 코드 스타일 일관성 유지
• 품질 향상: 흔한 코드 문제 방지

ESLint란 무엇인가요?

ESLint는 JavaScript 생태계에서 가장 인기 있는 코드 검사 도구로, 거의 모든 프론트엔드 프로젝트에서 사용됩니다. 하지만 성능 문제는 계속 지적받아 왔습니다:

• 대형 프로젝트 검사 시간 과다
• 플러그인 로딩에 많은 시간 소요
• 메모리 사용량 높음

Oxlint란 무엇인가요?

Oxlint는 OXC 프로젝트의 일부로, Rust로 작성되어 ESLint를 대체합니다. 특징은 다음과 같습니다:

• 극한의 속도: ESLint보다 50-100배 빠름
• 좋은 호환성: ESLint 규칙과 설정 형식 지원
• 바로 사용 가능: 복잡한 설정 없이 기본 추천 규칙 활성화
• 지속적 업데이트: 빠르게 ESLint 생태계를 따라잡고 있음

Oxlint 설치

Oxlint 설치는 매우 간단하며, 여러 방법 중 선택할 수 있습니다.

방법 1: 전역 설치

# npm 사용
npm install -g oxlint

# yarn 사용
yarn global add oxlint

# pnpm 사용
pnpm add -g oxlint

설치 후 어떤 디렉토리에서든 oxlint 명령을 사용할 수 있습니다.

방법 2: 프로젝트 내 설치

# 개발 의존성으로 설치
npm install oxlint --save-dev

그다음 package.json에 스크립트를 추가합니다:

{
  "scripts": {
    "lint": "oxlint ./src"
  }
}

방법 3: 설치 없이 바로 사용

# npx로 임시 실행
npx oxlint ./src

이 방법은 빠르게 체험하거나 전역 설치를 원치 않을 때 적합합니다.

첫 사용

설치가 완료되면, 실제로 체험해 봅시다.

단일 파일 검사

src/main.js 파일이 있다고 가정합니다:

// src/main.js
const unusedVar = 'I am not used';

function greeting(name) {
  console.log('Hello, ' + nam); // 철자 오류
  return 'Hello, ' + name;
}

greeting('World');

검사 실행:

oxlint src/main.js

출력 결과:

  ⚠ eslint(no-unused-vars): 'unusedVar' is defined but never used.
    ╭─[src/main.js:2:7]
  2 │   const unusedVar = 'I am not used';
    ·         ─────┬────
    ·              ╰── 'unusedVar' is defined here.
    ╰────────────────────────────────────

  ⚠ eslint(no-undef): 'nam' is not defined.
    ╭─[src/main.js:5:28]
  5 │     console.log('Hello, ' + nam);
    ·                            ─┬─
    ·                             ╰── 'nam' is not defined.
    ╰────────────────────────────────

  Finished in 3ms on 1 file with 0 errors and 2 warnings.

Oxlint가 두 가지 문제를 발견했습니다:

1. unusedVar가 정의되었지만 사용되지 않음
2. nam 변수가 정의되지 않음 (name이어야 함)

전체 프로젝트 검사

# src 디렉토리의 모든 파일 검사
oxlint ./src

# 여러 파일 형식 검사
oxlint "./src/**/*.{js,jsx,ts,tsx,vue}"

출력 형식:

  Finished in 12ms on 234 files with 0 errors and 5 warnings.

눈치채셨나요? 234개 파일을 12밀리초에 검사!

자동 수정

Oxlint는 일부 문제를 자동으로 수정할 수 있습니다:

# 수정 가능한 문제 자동 수정
oxlint ./src --fix

자동 수정 내용에는 다음이 포함됩니다:

• 사용하지 않는 변수 제거
• 간단한 코드 스타일 문제 수정
• 코드 형식 조정

실전: 기존 프로젝트에 Oxlint 추가하기

프로젝트에 Oxlint를 추가하는 전체 과정을 연습해 봅시다.

1단계: 테스트 프로젝트 생성

# 프로젝트 디렉토리 생성
mkdir my-project
cd my-project

# npm 초기화
npm init -y

# 소스 디렉토리 생성
mkdir src

테스트 파일 src/index.js 생성:

// src/index.js
import React from 'react';

// 사용하지 않는 변수
const API_URL = 'https://api.example.com';
const unusedConfig = { debug: true };

// 함수 정의
function fetchData(url) {
  // 에러 처리 누락
  return fetch(url).then(res => res.json());
}

// var 사용 (const/let 대신)
var data = null;

// 메인 함수
async function main() {
  data = await fetchData(API_URL);
  console.log('Data loaded:', data);
}

main();

2단계: Oxlint 설치

npm install oxlint --save-dev

3단계: package.json에 스크립트 추가

{
  "name": "my-project",
  "scripts": {
    "lint": "oxlint ./src",
    "lint:fix": "oxlint ./src --fix"
  },
  "devDependencies": {
    "oxlint": "^0.15.0"
  }
}

4단계: 첫 검사 실행

npm run lint

출력 예시:

  ⚠ eslint(no-unused-vars): 'unusedConfig' is defined but never used.
    ╭─[src/index.js:8:7]
  8 │   const unusedConfig = { debug: true };
    ·         ───────┬──────
    ·                ╰── 'unusedConfig' is defined here.
    ╰───────────────────────────────────────

  ⚠ eslint(no-var): Unexpected var, use let or const instead.
    ╭─[src/index.js:17:3]
 17 │   var data = null;
    ·   ─────┬────
    ·        ╰── Use `let` or `const` instead of `var`.
    ╰───────────────────────────────────────

  Finished in 4ms on 1 file with 0 errors and 2 warnings.

5단계: 출력 결과 이해하기

Oxlint의 출력에는 몇 가지 핵심 정보가 포함됩니다:

1. 규칙 이름: no-unused-vars, no-var 등
2. 문제 위치: 파일명, 줄 번호, 열 번호
3. 문제 설명: 문제를 명확하게 설명
4. 통계 정보: 검사 소요 시간, 파일 수, 오류 및 경고 수

6단계: 자동 수정

npm run lint:fix

수정 후 src/index.js의 변화:

// src/index.js
import React from 'react';

// 사용하지 않는 변수가 제거됨
const API_URL = 'https://api.example.com';

// 함수 정의
function fetchData(url) {
  // 에러 처리 누락
  return fetch(url).then(res => res.json());
}

// var가 let으로 변경됨
let data = null;

// 메인 함수
async function main() {
  data = await fetchData(API_URL);
  console.log('Data loaded:', data);
}

main();

설정 파일 입문

Oxlint는 설정 파일로 규칙을 커스터마이즈할 수 있습니다.

설정 파일 생성

프로젝트 루트에 oxlint.json을 생성합니다:

{
  "rules": {
    "no-unused-vars": "error",
    "no-console": "warn",
    "no-var": "error",
    "prefer-const": "warn"
  }
}

규칙 레벨

각 규칙은 세 가지 레벨로 설정할 수 있습니다:

레벨	설명
"off" 또는 0	규칙 끄기
"warn" 또는 1	경고, CI를 중단하지 않음
"error" 또는 2	오류, 0이 아닌 종료 코드 반환

자주 사용하는 규칙 설정

{
  "rules": {
    // 변수 관련
    "no-unused-vars": "error",
    "no-undef": "error",
    "prefer-const": "warn",

    // 코드 스타일
    "no-var": "error",
    "eqeqeq": ["error", "always"],
    "curly": ["warn", "multi-line"],

    // 모범 사례
    "no-console": "warn",
    "no-debugger": "error",
    "no-alert": "warn"
  }
}

파일 무시

.oxlintignore 파일을 생성하여 검사가 필요 없는 디렉토리를 제외합니다:

# .oxlintignore
node_modules/
dist/
build/
*.min.js
*.d.ts

VS Code 통합

편집기에서 실시간으로 코드 문제를 보면 개발 효율이 크게 향상됩니다.

플러그인 설치

1. VS Code 열기
2. “oxlint” 플러그인 검색
3. Oxlint 플러그인 설치

플러그인 설정

.vscode/settings.json에 설정 추가:

{
  "oxlint.enable": true,
  "oxlint.run": "onSave",
  "oxlint.configPath": "./oxlint.json"
}

효과 확인

플러그인 설치 후, 파일 저장 시 자동으로 검사합니다:

// 편집기에서 바로 물결선으로 표시
const unused = 'I am never used';  // ~~~~~~ 'unused' is defined but never used

var oldStyle = 'use let/const';    // ~~~ Use `let` or `const` instead of `var`.

물결선 위에 마우스를 올리면 상세한 문제 설명과 수정 제안을 볼 수 있습니다.

자주 묻는 질문

Oxlint가 ESLint를 완전히 대체할 수 있나요?

아직 완전히 대체할 수는 없지만, 대부분의 상황에서 충분합니다.

Oxlint의 장점:

• 매우 빠른 속도, 일상 개발에 적합
• 대부분의 자주 사용하는 규칙 지원
• 간단한 설정, 바로 사용 가능

현재 한계:

• 일부 고급 규칙 미구현
• 플러그인 생태계가 ESLint만큼 풍부하지 않음
• 프레임워크별 규칙(예: vue-eslint-plugin) 지원 제한

ESLint에서 마이그레이션하려면?

점진적 마이그레이션 전략:

1. 병렬 실행: ESLint와 Oxlint를 동시에 유지

   {
     "scripts": {
       "lint": "oxlint ./src && eslint ./src"
     }
   }

2. 단계적 전환: 먼저 Oxlint로 일상 개발을 처리하고, CI에서는 ESLint 유지

3. 완전 마이그레이션: Oxlint가 모든 요구사항을 충족하면 ESLint 제거

Oxlint와 ESLint의 검사 결과가 다른가요?

이는 정상입니다. 이유는 다음과 같습니다:

• 규칙 구현 세부사항에 차이가 있을 수 있음
• 기본 활성화된 규칙 세트가 다름
• 일부 규칙이 아직 구현되지 않음

해결 방법: 설정 파일로 규칙 통일.

어떤 파일 형식을 지원하나요?

Oxlint는 다음을 지원합니다:

• JavaScript (.js, .mjs, .cjs)
• TypeScript (.ts, .tsx, .mts, .cts)
• JSX (.jsx)
• Vue (.vue)
• Astro (.astro)
• Svelte (.svelte)

성능 비교 실측

실제 데이터로 확인해 봅시다.

테스트 환경

• 프로젝트: 중형 프론트엔드 프로젝트
• 파일 수: 약 500개 .ts/.tsx 파일
• 장비: MacBook Pro M1, 16GB 메모리

테스트 결과

도구	첫 실행 시간	증분 실행 시간
ESLint	42초	38초
Oxlint	0.6초	0.4초

Oxlint가 ESLint보다 약 70배 빠릅니다!

이는 다음을 의미합니다:

• Git pre-commit 훅이 분 단위에서 초 단위로 단축
• CI 파이프라인 크게 단축
• 개발 피드백 주기 현저히 단축

요약

본문에서는 Oxlint의 핵심 사용법을 소개했습니다:

내용	설명
설치	npm install -g oxlint 또는 npx oxlint
파일 검사	oxlint ./src
자동 수정	oxlint ./src --fix
설정 파일	oxlint.json으로 규칙 정의
편집기 통합	VS Code Oxlint 플러그인 설치

Oxlint의 핵심 가치: 코드 검사를 “대기”에서 “즉시 완료”로 변화.

다음 단계

Oxlint의 고급 설정과 전체 규칙 목록을 더 알고 싶으신가요? **OXC 한국어 문서 - Oxlint 챕터**를 방문하세요.

다음 글에서는 Oxfmt를 배워보겠습니다. 코드 포맷팅도 빠르게 만들어 봅시다!

---

💡 관련 읽기:

• 이전 글: 프론트엔드 도구가 너무 느린가요? Rust로 작성된 OXC를 사용해 보세요
• OXC 한국어 문서