ESLint — 코드 품질을 검사하는 정적 분석 도구

ESLint는 코드를 실행하지 않고도 문제를 찾아내는 정적 분석 도구입니다.

정적 분석(Static Analysis): 프로그램을 실행하지 않은 채 소스코드 자체를 읽어 오류·패턴을 탐지하는 기법

런타임에서야 드러나는 버그, 팀마다 다르게 쓰이는 코딩 스타일, 사용되지 않는 변수 같은 문제를 커밋 전에 잡아낼 수 있습니다. Prettier가 "어떻게 생겼는가(formatting)"를 담당한다면, ESLint는 "어떻게 작동하는가(quality)"를 담당합니다.

---

핵심 개념

1. Rule

Rule은 ESLint에서 코드를 검사하는 가장 작은 단위의 규칙입니다. 각 Rule은 하나의 코드 패턴을 검사하고, 세 가지 심각도 중 하나로 설정됩니다.

대표적인 내장 Rule 예시입니다.

// no-unused-vars: 선언했지만 쓰지 않는 변수를 금지
const count = 42; // 사용하지 않으면 error 또는 warn 발생

// eqeqeq: == 대신 === 사용을 강제
if (a == b) { }  // 위반 → if (a === b) { } 로 고쳐야 함

// no-console: console.log 사용 금지
console.log("디버그"); // warn 또는 error 처리 가능

// eslint.config.js 에서 Rule 설정 예시
rules: {
  "no-unused-vars": "error",
  "eqeqeq": ["error", "always"],
  "no-console": "warn",
}

Rule마다 옵션을 배열 형태로 전달할 수도 있습니다. "eqeqeq": ["error", "always"]처럼 첫 번째 원소가 심각도, 두 번째 이후가 Rule 전용 옵션입니다.

---

2. Config

Config는 Rule, 환경(env), 파서, 플러그인 등의 설정을 모아놓은 파일입니다. ESLint v9부터 Flat Config 형식인 eslint.config.js가 기본입니다.

// eslint.config.js (Flat Config, ESLint v9+)
import js from "@eslint/js";
import globals from "globals";

export default [
  js.configs.recommended,          // ESLint 권장 규칙 세트를 extends
  {
    languageOptions: {
      globals: globals.browser,    // 브라우저 전역 변수(window, document 등) 허용
      ecmaVersion: 2022,
      sourceType: "module",
    },
    rules: {
      "no-unused-vars": "error",
      "no-console": "warn",
    },
  },
];

extends(구 형식)나 js.configs.recommended(Flat Config 형식)처럼 공유 설정(Shareable Config)을 가져와 기반으로 삼고, 팀 전용 규칙을 추가하는 패턴이 일반적입니다.

eslint.config.js 계층 구조

  js.configs.recommended   <-- 공유 설정 (베이스)
         +
  팀 공통 rules            <-- 프로젝트 공유 설정
         +
  파일별 override rules    <-- 특정 파일/폴더 전용 규칙

---

3. Plugin

Plugin은 ESLint에 새로운 Rule을 추가하는 패키지입니다. 내장 Rule만으로는 커버할 수 없는 프레임워크·환경 특화 규칙을 제공합니다.

ESLint 내장 Rule
      +
eslint-plugin-react        → React JSX, Hooks 관련 규칙
@typescript-eslint/eslint-plugin → TypeScript 타입 인식 규칙
eslint-plugin-jsx-a11y     → 접근성(aria) 관련 규칙
eslint-plugin-import       → import/export 순서·경로 규칙

Flat Config에서 Plugin 적용 방법입니다.

import reactPlugin from "eslint-plugin-react";
import tsPlugin from "@typescript-eslint/eslint-plugin";

export default [
  {
    plugins: {
      react: reactPlugin,
      "@typescript-eslint": tsPlugin,
    },
    rules: {
      "react/jsx-key": "error",              // 배열 JSX에 key prop 필수
      "react/react-in-jsx-scope": "off",     // React 17+ 이후 불필요
      "@typescript-eslint/no-explicit-any": "warn",
    },
  },
];

Plugin 이름을 plugins 객체의 키로 등록한 뒤, rules에서 "플러그인키/규칙명" 형태로 참조합니다.

---

4. Parser

ESLint는 기본적으로 JavaScript를 이해하는 파서를 내장합니다. 하지만 TypeScript나 JSX 같은 비표준 문법은 별도 파서(Parser)가 필요합니다.

파서는 소스코드를 읽어 AST(Abstract Syntax Tree)로 변환합니다.

소스코드 (text)
      |
   [Parser]         ← @typescript-eslint/parser, @babel/eslint-parser 등
      |
   AST (tree)
      |
  [ESLint Rule]     ← 트리 노드를 순회하며 패턴 검사
      |
  오류/경고 리포트

// TypeScript 프로젝트에서 파서 설정
import tsParser from "@typescript-eslint/parser";
import tsPlugin from "@typescript-eslint/eslint-plugin";

export default [
  {
    files: ["**/*.ts", "**/*.tsx"],
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        project: "./tsconfig.json",  // 타입 정보 활용 규칙 사용 시 필요
      },
    },
    plugins: {
      "@typescript-eslint": tsPlugin,
    },
    rules: {
      "@typescript-eslint/no-floating-promises": "error",
    },
  },
];

parserOptions.project를 지정하면 @typescript-eslint의 타입 인식(type-aware) 규칙을 사용할 수 있습니다. 단, tsconfig를 읽으므로 검사 속도가 다소 느려집니다.

---

5. Ignore

모든 파일을 검사할 필요는 없습니다. 빌드 결과물, 의존성 폴더, 자동 생성 파일은 검사에서 제외해야 합니다.

방법 1: .eslintignore 파일 (구 형식)

# .eslintignore
node_modules/
dist/
build/
coverage/
*.min.js

방법 2: Flat Config의 ignores 키 (권장)

// eslint.config.js
export default [
  {
    ignores: [
      "node_modules/**",
      "dist/**",
      "build/**",
      "coverage/**",
      "**/*.min.js",
    ],
  },
  // ... 나머지 설정
];

Flat Config에서는 ignores만 담긴 설정 객체를 배열 맨 앞에 두는 것이 관례입니다. ignores를 전역으로 적용하려면 다른 키 없이 단독 객체로 둬야 합니다.

---

6. Auto Fix

ESLint의 Rule 중 일부는 자동 수정(Auto Fix)을 지원합니다. 문제를 찾는 것에서 그치지 않고 코드를 직접 고쳐줍니다.

CLI에서 수정:

# 현재 디렉토리 전체 검사
npx eslint .

# 수정 가능한 문제 자동 수정
npx eslint . --fix

# 특정 파일만
npx eslint src/index.ts --fix

VS Code 에디터 연동:

// .vscode/settings.json
{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.validate": ["javascript", "typescript", "typescriptreact"]
}

저장할 때마다 ESLint가 자동 수정 가능한 Rule을 적용합니다.

자동 수정 가능 여부 확인:

Rule 문서 페이지에서 [fixable] 표시가 있으면 fixable
예시:
  no-extra-semi     → fixable (불필요한 세미콜론 제거)
  prefer-const      → fixable (let → const 변환)
  no-unused-vars    → NOT fixable (삭제 여부는 사람이 판단)
  eqeqeq            → fixable (== → === 변환)

Auto Fix는 안전하게 변환 가능한 경우에만 동작합니다. 로직이 바뀔 위험이 있는 Rule은 수동 수정을 요구합니다.

---

설치 및 기본 설정

# ESLint 설치 및 초기화
npm init @eslint/config@latest

초기화 명령은 프로젝트 유형을 물어보고 eslint.config.js를 자동 생성합니다. TypeScript + React 프로젝트라면 필요한 파서와 플러그인도 함께 설치해 줍니다.

# package.json에 스크립트 추가 후
npx eslint src/
npx eslint src/ --fix

// package.json
{
  "scripts": {
    "lint": "eslint src/",
    "lint:fix": "eslint src/ --fix"
  }
}

ESLint를 CI 파이프라인에 포함시켜 "error" 수준 위반이 있으면 빌드를 실패시키는 것이 일반적인 운영 방식입니다.