ESLint 10 마이그레이션 가이드: 역대급 업데이트의 모든 것

ESLint 10 나왔어요. 그냥 마이너 업데이트 아닙니다. 그동안 붙잡고 있던 .eslintrc 설정 시스템? 완전 삭제—deprecated 아니고 삭제예요. --env 플래그? 없어졌어요. Node.js 18? 더 이상 지원 안 해요.

ESLint 팀이 확실히 정리해줬어요: flat config만이 유일한 길.

마이그레이션 미뤄왔다면 2026년 1월이 데드라인이에요. ESLint 9는 이제 유지보수 모드고, ESLint 10이 현재예요. 이 가이드로 CI 파이프라인 안 깨고 넘어갑시다.

ESLint 10의 새로운 점

마이그레이션 전에 뭐가 바뀌었는지 봅시다.

Node.js 20.19.0+ 필수

ESLint 10은 Node.js 18, 19, 21, 23 지원 끊었어요. 필요한 거:

Node.js ^20.19.0 (20.x에서 20.19.0 이상)
Node.js ^22.13.0 (22.x LTS에서 22.13.0 이상)
Node.js >=24.0.0 (24.x Current)

CI/CD 파이프라인 확인하세요. 옛날 Node 버전에서 빌드 바로 깨져요.

node --version  # v20.19.0 이상이어야 함

.eslintrc 완전 삭제

이게 제일 중요해요. ESLint 10은 레거시 설정 관련된 거 전부 날려버렸어요:

삭제됨	대체
`.eslintrc.*` 파일	`eslint.config.js`
`.eslintignore`	config의 `ignores` 배열
`--env` 플래그	`languageOptions`의 `globals`
`--rulesdir` 플래그	직접 플러그인 import
`--resolve-plugins-relative-to`	ES 모듈 import
`/* eslint-env */` 주석	이제 에러로 리포트됨
`ESLINT_USE_FLAT_CONFIG` 환경변수	항상 flat config
`LegacyESLint` API	완전 삭제

프로젝트에 아직 .eslintrc.json 있으면 ESLint 10은 그냥 무시해요.

새로운 설정 파일 탐색

ESLint 10은 config 파일 찾는 방식 바뀌었어요:

ESLint 9 (옛날 방식):

CWD에서 위로 올라가며 eslint.config.js 찾기

ESLint 10 (새 방식):

각 린트하는 파일의 디렉토리에서 위로 올라가며 eslint.config.js 찾기

모노레포에서 엄청 좋아요. 각 패키지가 자기 eslint.config.js 가질 수 있고, ESLint가 자동으로 찾아요.

my-monorepo/
├── eslint.config.js          # 루트 config (폴백)
├── packages/
│   ├── web/
│   │   ├── eslint.config.js  # 웹 전용 config
│   │   └── src/
│   └── api/
│       ├── eslint.config.js  # API 전용 config
│       └── src/

JSX 레퍼런스 트래킹

ESLint 10은 이제 JSX 엘리먼트 레퍼런스를 정확하게 추적해요:

커스텀 컴포넌트가 제대로 레퍼런스로 추적됨
no-unused-vars가 JSX에서 제대로 작동
기존 코드에 새 경고 뜰 수 있음 (v9에서 false positive였던 거)

// ESLint 10은 이제 Button을 레퍼런스로 정확히 봐요
import { Button } from './components';

function App() {
  return <Button>Click me</Button>;  // Button 추적됨
}

업데이트된 `eslint:recommended`

recommended 룰셋이 업데이트됐어요. 마이그레이션 후 ESLint 돌려서 새 위반 잡으세요.

ESLint 9에서 단계별 마이그레이션

1단계: Node.js 버전 확인

node --version
# v20.19.0 미만이면 먼저 업그레이드

CI/CD를 Node.js 20.x LTS나 22.x로 업데이트하세요.

2단계: ESLint랑 의존성 업데이트

npm install eslint@10 --save-dev

# TypeScript 쓰면 TypeScript ESLint도 업데이트
npm install @typescript-eslint/eslint-plugin@latest @typescript-eslint/parser@latest --save-dev

# 다른 플러그인들도 업데이트
npm install eslint-plugin-react@latest eslint-plugin-react-hooks@latest --save-dev

3단계: Config 마이그레이션 (아직 안 했으면)

아직 .eslintrc 쓰고 있으면 마이그레이션 도구 사용:

npx @eslint/migrate-config .eslintrc.json

eslint.config.mjs 파일 생성돼요. 검토하고 조정하세요.

4단계: v10 호환성 위해 Flat Config 업데이트

이미 eslint.config.js 있으면 v10 전용 업데이트 확인:

`eslint-env` 주석 제거

// ❌ ESLint 10은 이거 에러로 리포트
/* eslint-env browser, node */

// ✅ config에서 globals 사용
import globals from "globals";

export default [
  {
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node,
      }
    }
  }
];

5단계: 레거시 파일 삭제

rm .eslintrc.* .eslintignore 2>/dev/null || true

6단계: VS Code 설정 업데이트

{
  "eslint.useFlatConfig": true
}

참고: eslint.useFlatConfig 설정은 이제 기본이에요. 삭제해도 됨.

7단계: 테스트

npx eslint .

업데이트된 eslint:recommended나 JSX 트래킹에서 새 위반 고치세요.

ESLint 10 완전한 설정 예제

TypeScript 프로젝트

// eslint.config.js
import js from "@eslint/js";
import typescript from "typescript-eslint";
import globals from "globals";

export default typescript.config(
  js.configs.recommended,
  ...typescript.configs.recommendedTypeChecked,
  {
    languageOptions: {
      globals: globals.node,
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
  {
    files: ["**/*.js", "**/*.mjs"],
    ...typescript.configs.disableTypeChecked,
  },
  {
    ignores: ["dist/**", "node_modules/**"],
  }
);

React + TypeScript (Next.js)

// eslint.config.mjs
import js from "@eslint/js";
import typescript from "typescript-eslint";
import react from "eslint-plugin-react";
import reactHooks from "eslint-plugin-react-hooks";
import jsxA11y from "eslint-plugin-jsx-a11y";
import next from "@next/eslint-plugin-next";
import globals from "globals";

export default typescript.config(
  js.configs.recommended,
  ...typescript.configs.recommended,
  
  // React + JSX
  {
    files: ["**/*.{jsx,tsx}"],
    plugins: {
      react,
      "react-hooks": reactHooks,
      "jsx-a11y": jsxA11y,
    },
    languageOptions: {
      globals: globals.browser,
      parserOptions: {
        ecmaFeatures: { jsx: true },
      },
    },
    settings: {
      react: { version: "detect" },
    },
    rules: {
      ...react.configs.recommended.rules,
      ...react.configs["jsx-runtime"].rules,
      ...reactHooks.configs.recommended.rules,
      ...jsxA11y.configs.recommended.rules,
    },
  },
  
  // Next.js
  {
    plugins: {
      "@next/next": next,
    },
    rules: {
      ...next.configs.recommended.rules,
      ...next.configs["core-web-vitals"].rules,
    },
  },
  
  {
    ignores: [".next/**", "node_modules/**", "out/**"],
  }
);

패키지별 Config 있는 모노레포

// 루트: eslint.config.js
import js from "@eslint/js";
import typescript from "typescript-eslint";

// 모든 패키지가 상속받는 기본 config
export default typescript.config(
  js.configs.recommended,
  ...typescript.configs.recommended,
  {
    ignores: ["**/dist/**", "**/node_modules/**"],
  }
);

// packages/web/eslint.config.js
import baseConfig from "../../eslint.config.js";
import react from "eslint-plugin-react";
import globals from "globals";

export default [
  ...baseConfig,
  {
    files: ["**/*.{jsx,tsx}"],
    plugins: { react },
    languageOptions: {
      globals: globals.browser,
    },
    rules: {
      ...react.configs.recommended.rules,
    },
  },
];

ESLint 10의 새로운 찾기 방식이 자동으로 각 파일에 가장 가까운 eslint.config.js 써요.

흔한 마이그레이션 에러와 해결법

Error: "ESLint requires Node.js version ^20.19.0 || ^22.0.0 || >=24.0.0"

해결: Node.js를 20.19.0 이상으로 업그레이드.

# nvm 사용 시
nvm install 22
nvm use 22

Error: "eslint-env is no longer supported"

해결: /* eslint-env */ 주석 제거하고 globals 사용:

import globals from "globals";

{
  languageOptions: {
    globals: globals.browser
  }
}

Error: "ConfigArray.normalize is not a function"

해결: @eslint/eslintrc를 최신 버전으로 업데이트:

npm install @eslint/eslintrc@latest

Error: 모노레포에서 "Cannot find config"

해결: ESLint 10은 CWD가 아닌 파일 디렉토리에서 찾아요. 둘 중 하나:

각 패키지에 eslint.config.js 추가, 또는
루트에서 명시적 파일 패턴으로 ESLint 실행

Warning: JSX 트래킹에서 새 위반

해결: v9가 놓친 실제 이슈일 가능성 높아요. 각각 검토하세요. false positive면 해당 줄에서 규칙 비활성화.

마이그레이션 체크리스트

마이그레이션할 때 이 체크리스트 쓰세요:

지금 마이그레이션 해야 할까?

네. 이유:

ESLint 9는 유지보수 모드—새 기능 없고 중요 수정만
플러그인 생태계가 이동 중—인기 플러그인들 v9 지원 끊는 중
새 탐색 알고리즘 강력함—특히 모노레포에서
JSX 트래킹이 진짜 버그 잡음—기존 코드에 몰랐던 이슈 있을 수 있음

마이그레이션은 대부분 기계적이에요. v9에서 이미 flat config로 옮겼으면 90% 끝난 거예요. 아직 .eslintrc면 지금이 때—더 이상 여유 없어요.

마무리

ESLint 10은 과거랑 완전히 끊은 거예요. 레거시 설정 시스템은 영영 사라졌어요. 대신 얻는 거:

더 심플해요: 파일 하나, 포맷 하나, 마법 없음
모노레포에서 더 편해요: 패키지별 config가 그냥 돼요
더 정확한 린팅: JSX 트래킹이 실제 이슈 잡음
미래 대비: 생태계가 가는 방향에 있음

마이그레이션 한두 시간 걸릴 수 있지만, 앞으로 몇 년간 ESLint 릴리즈 대비 완료.

기술 부채 하나 줄었네요. 이제 config 업데이트하러 가세요! 🚀