ESLint Flat Config 마이그레이션 완벽 가이드

ESLint Flat Config란

ESLint v9부터 기본이 된 Flat Config는 기존 .eslintrc 파일 대신 eslint.config.js를 사용하는 새로운 설정 시스템입니다. 더 직관적이고 예측 가능한 설정 방식을 제공합니다.

기존 방식 vs Flat Config

// 기존 .eslintrc.json (레거시)
{
  "env": { "browser": true, "es2021": true },
  "extends": [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "parser": "@typescript-eslint/parser",
  "plugins": ["react", "@typescript-eslint"],
  "rules": {
    "no-unused-vars": "warn",
    "react/react-in-jsx-scope": "off"
  }
}

// 새로운 eslint.config.js (Flat Config)
import globals from "globals";
import tseslint from "typescript-eslint";
import react from "eslint-plugin-react";

export default [
  { files: ["**/*.{ts,tsx}"] },
  { languageOptions: { globals: globals.browser } },
  ...tseslint.configs.recommended,
  react.configs.flat.recommended,
  {
    rules: {
      "no-unused-vars": "warn",
      "react/react-in-jsx-scope": "off"
    }
  }
];

마이그레이션 단계

# 1. 호환성 유틸리티 설치
npm install -D @eslint/compat @eslint/js

# 2. eslint.config.js 생성
# 3. 기존 .eslintrc 삭제
# 4. .eslintignore → ignores로 이동

# 자동 마이그레이션 도구
npx @eslint/migrate-config .eslintrc.json

실전 설정 예제 (React + TypeScript)

import globals from "globals";
import js from "@eslint/js";
import tseslint from "typescript-eslint";
import react from "eslint-plugin-react";
import reactHooks from "eslint-plugin-react-hooks";
import jsxA11y from "eslint-plugin-jsx-a11y";
import prettier from "eslint-config-prettier";

export default tseslint.config(
  {
    ignores: [
      "dist/**",
      "node_modules/**",
      "*.config.js",
      "coverage/**"
    ]
  },
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    files: ["**/*.{tsx,jsx}"],
    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,
      ...reactHooks.configs.recommended.rules,
      "react/react-in-jsx-scope": "off",
      "react/prop-types": "off"
    }
  },
  {
    files: ["server/**/*.ts"],
    languageOptions: {
      globals: { ...globals.node }
    }
  },
  {
    files: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
    languageOptions: {
      globals: { ...globals.jest }
    },
    rules: {
      "@typescript-eslint/no-explicit-any": "off"
    }
  },
  prettier
);

레거시 플러그인 호환

import { fixupPluginRules } from "@eslint/compat";
import importPlugin from "eslint-plugin-import";

export default [
  {
    plugins: {
      import: fixupPluginRules(importPlugin)
    },
    rules: {
      "import/order": ["error", {
        "groups": ["builtin", "external", "internal"],
        "newlines-between": "always"
      }]
    }
  }
];

주요 변경사항 정리

• Flat Config는 ES 모듈로 작성하므로 동적 설정이 자연스러움
• 설정 배열의 순서가 곧 우선순위 (나중이 우선)
• @eslint/compat으로 대부분의 레거시 플러그인 사용 가능
• ESLint v9부터 Flat Config가 기본, .eslintrc는 더 이상 자동 인식되지 않음
• 팀 전체 마이그레이션이 어려우면 ESLINT_USE_FLAT_CONFIG=false로 임시 비활성화