ESLint flat config — eslintrc에서 마이그레이션 핵심

ESLint 9가 기본으로 채택한 flat config는 기존 .eslintrc와 형태가 꽤 다릅니다. 단순한 이름 변경이 아니라 설정 파일이 JS 모듈이고, extends가 없으며, 파일 패턴별 적용이 명시적입니다. 마이그레이션 핵심만 추리면 큰 어려움 없이 옮길 수 있습니다.

1. 파일 위치와 이름

.eslintrc.json   →  eslint.config.js (또는 .mjs / .ts)
.eslintignore    →  flat config의 ignores 옵션

eslint.config.js가 프로젝트 루트에 있어야 합니다. 자동으로 발견됩니다.

2. 가장 단순한 형태

1// eslint.config.js
2import js from '@eslint/js';
3
4export default [
5  js.configs.recommended,
6  {
7    rules: {
8      'no-console': 'warn',
9    },
10  },
11];

배열의 각 요소가 "어떤 파일에 어떤 설정을 적용할지" 정의합니다.

3. extends가 사라진 이유

flat config는 extends를 명시적인 spread로 대체합니다.

1import js from '@eslint/js';
2import tseslint from 'typescript-eslint';
3
4export default [
5  js.configs.recommended,
6  ...tseslint.configs.recommended,
7  {
8    rules: {
9      '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
10    },
11  },
12];

tseslint.configs.recommended는 배열을 반환하므로 spread로 펼칩니다. 명시적이지만 코드가 살짝 길어지는 게 단점입니다.

4. 파일별 설정

files와 ignores로 패턴을 명시합니다.

1export default [
2  {
3    files: ['**/*.{ts,tsx}'],
4    rules: { /* TS만 */ },
5  },
6  {
7    files: ['**/*.test.ts'],
8    rules: { '@typescript-eslint/no-explicit-any': 'off' },
9  },
10  {
11    ignores: ['dist/**', '.next/**', 'node_modules/**'],
12  },
13];

기존 overrides가 사라지고, 그냥 객체를 추가하는 방식입니다.

5. React 프로젝트 예제

1import js from '@eslint/js';
2import tseslint from 'typescript-eslint';
3import reactHooks from 'eslint-plugin-react-hooks';
4import reactRefresh from 'eslint-plugin-react-refresh';
5
6export default [
7  { ignores: ['dist/**', '.next/**', 'node_modules/**'] },
8  js.configs.recommended,
9  ...tseslint.configs.recommended,
10  {
11    files: ['**/*.{ts,tsx}'],
12    plugins: {
13      'react-hooks': reactHooks,
14      'react-refresh': reactRefresh,
15    },
16    rules: {
17      ...reactHooks.configs.recommended.rules,
18      'react-refresh/only-export-components': 'warn',
19    },
20  },
21];

6. 주의할 점

• parserOptions, env, extends가 모두 사라졌습니다. 대체 방법이 다릅니다 (languageOptions, plugin spread).
• 일부 플러그인이 아직 flat config를 공식 지원하지 않을 수 있습니다. @eslint/compat의 fixupPluginRules로 호환 가능.
• IDE(VS Code) ESLint 확장은 1.0.0+에서 자동 지원합니다. 구버전은 설정 필요.
• 마이그레이션은 @eslint/migrate-config 도구가 자동으로 변환해줍니다.

7. 정리

기존	flat config
.eslintrc.json	eslint.config.js
extends: ['...']	spread (...tseslint.configs.recommended)
overrides: [{...}]	배열에 객체 추가
.eslintignore	{ ignores: [...] }
env: { browser: true }	languageOptions.globals

처음에는 낯설지만, 한 번 옮기면 "어떤 파일에 어떤 룰이 어떤 출처로 적용되는지"가 더 명확해집니다. 자동 마이그레이션 도구로 시작 + 출력된 설정을 직접 정리하는 흐름이 가장 빠릅니다.

참고: ESLint Configuration Migration Guide.