[Frontend] ESLint v9 공식 문서 뜯어보기

목차 (OPEN)

• 📑 들어가며
• 🟥 typescript-eslint란
• 🟧 defineConfig( )와 tseslint.config( )의 관계
• 🟨 Flat Config의 등장과 변화의 배경
• 🟩 Vite 템플릿이 만들어준 기본 ESLint 설정 뜯어보기
• 🟦 처음 던졌던 다섯 가지 질문의 답
• 📚 결론

 

 

 

 

 

 

📑 들어가며

그동안 마감 기한이 촉박한 프로젝트들로 프론트엔드에 입문하다 보니,

기본적인 개념들은 하나도 모른채로 돌아가기만 하는 코드를 작성하기만 했던 것 같다.

 

그래서 이번에는 한 번쯤은 제대로 짚고 가야겠다는 생각으로,

ESLint랑 TypeScript에 대해 공식 문서를 직접 읽어보기로 했다.

 

그러나 .. 역시 공식 문서 답게 영어이다 보니까

개념이 한 번에 와닿지가 않아서 읽는데 꽤나 힘들었다 ..😵‍💫

 

특히 요즘 생태계가

• ESLint v9 + flat config
• typescript-eslint 단일 패키지
• defineConfig, extends, globalIgnores

위와 같은 새로운 키워드들로 빠르게 넘어가고 있어서

그동안처럼 다른 사람들이 작성해둔 블로그나 템플릿을 참고해서

감으로 세팅하던 방식으로는 한계가 있었다 ..😭

 

 

그래서 이 포스팅에다가 내가 실제로 공식 문서를 읽으면서 이해한 내용을

한국어로 다시 정리해 두고자 한다.

 

특히 아래의 내용들을 중심으로 포스팅을 정리하고자 하니, 포스팅을 읽기 전에 참고해두면 좋을 것 같다.

• 왜 @typescript-eslint/parser와 eslint-plugin 대신에 typescript-eslint 패키지 하나로 정리되었는가
• 새로운 방식인 flat config가 어떤 개념인가
• defineConfig가 하는 역할과, 예전의 tseslint.config( ... )와의 관계는 무엇인가
• flat config에서 다시 돌아온 extends의 의미와 사용 패턴은 무엇인가
• .eslintignore 대신 설정 파일 안에서 사용하는 galobalIgnores란 무엇인가

 

 

---

🟥 typescript-eslint란

typescript-eslint | typescript-eslint

 

 

프론트엔드 개발을 하다 보면 ESLint와 TypeScript를 함께 쓰는 경우가 많다.

하지만 이 둘은 원래부터 잘 통하는 관계가 아니었다구 한다 😶

 

ESLint는 JavaScript 전용 린터였고,

TypeScript는 JS의 상위 확장 언어이기 때문에

단순히 ESLint만 설치해서는 TS 문법이나 타입 정보를 제대로 이해하지 못했다.

 

그래서 예전에는 아래 두 개의 패키지를 따로 설치해야 했다고 한다.

• @typescript-eslint/parser 👉🏻 TS 코드를 ESLint가 이해할 수 있는 JS AST로 바꿔주는 역할
• @typescript-eslint/eslint-plugin 👉🏻 TS 전용 ESLint 규칙들을 추가로 제공하는 역할

 

즉, parser가 TS 코드를 해석해주는 역할을 하고,

plugin은 TS 문법에 맞는 규칙 세트를 제공하는 확장팩이었다고 생각하면 된다.

 

 

 

그러나 최근에는 이 두 패키지를 별도로 설치하지 않고도 사용할 수 있다 !-!

typescript-eslint라는 통합 패키지 하나에 아래의 구성 요소들이 모두 들어있기 때문이다 👍🏻

• parser 👉🏻 TS 코드를 ESLint가 이해할 수 있게 파싱
• plugin 👉🏻 TS 관련 ESLint 규칙 세트 제공
• configs 👉🏻 여러 추천 규칙 세트를 담고 있는 객체 (tseslint.configs.recommended 등)
• FlatConfig 👉🏻 flat config 방식에서 사용하는 타입 정의

(참고로 config 유틸은 예전 방식이고, 현재는 deprecated이기 때문에 사용하지 않는다.)

 

 

설치 명령도 훨씬 간단해졌다 !

예전에는 이렇게 두 개를 따로 설치했다면,

npm install -D @typescript-eslint/parser @typescript-eslint/eslint-plugin

 

이제는 이렇게만 해주면 된다.

npm install -D typescript-eslint

 

 

---

🟧 defineConfig( )와 tseslint.config( )의 관계

Evolving flat config with extends - ESLint - Pluggable JavaScript Linter

 

ESLint는 원래 .eslintrc 방식의 설정 파일을 사용했지만,

ESLint v9 부터는 flat config 구조가 도입되면서

설정 방식을 좀 더 코드 중심 + 타입 안전하게 바꾸게 되었다고 한다.

 

이때, typescript-eslint가 flat config를 쉽게 작성할 수 있도록

tseslint.config( ... )라는 헬퍼 함수를 따로 제공했었지만,

이제는 ESLint 자체에서 defineConfig( ... )를 공식 지원하게 되면서

이 기능이 ESLint 코어로 완전히 통합되었다고 한다.

 

 

즉, 예전 방식은 아래처럼 여러 개의 config object(설정 객체)를 받아서

한 번에 flatten(병합) 해주는 유틸리티였다면,

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,       // 기본 JS 규칙
  tseslint.configs.recommended,     // TS용 추천 규칙
  {
    rules: {
      'no-console': 'warn',         // 커스텀 규칙 추가
    },
  },
);

 

이제는 ESLint 코어에서 defineConfig( )라는 함수를 공식 제공하기 때문에

아래와 같이 변경되었다고 보면 된다.

import eslint from '@eslint/js';
import { defineConfig } from 'eslint/config';
import tseslint from 'typescript-eslint';

export default defineConfig(
  eslint.configs.recommended,
  tseslint.configs.recommended,
  {
    rules: {
      'no-console': 'warn',
    },
  },
);

 

예시에서 볼 수 있듯이 그냥 tseslint.config( ... )가 defineConfig( ... )로 이름만 바꼈다고 보면 된다 ㅋㅋ

 

 

참고로 parser와 plugin 등을 직접 지정하고 싶다면 아래와 같이 작성해주면 된다.

import eslint from '@eslint/js';
import { defineConfig } from 'eslint/config';
import tseslint from 'typescript-eslint';

export default defineConfig({
  plugins: {
    '@typescript-eslint': tseslint.plugin,
  },
  languageOptions: {
    parser: tseslint.parser,
    parserOptions: {
      projectService: true,
    },
  },
  rules: {
    '@typescript-eslint/no-floating-promises': 'error',
    // ...
  },
});

 

 

---

🟨 Flat Config의 등장과 변화의 배경

ESLint는 오랫동안 .eslintrc 파일을 사용해왔지만,

v9 버전부터는 Flat Config라는 새로운 설정 구조가 기본값으로 자리잡았다.

 

이전의 .eslintrc는 YAML/JSON 기반으로

"extends"나 "plugins" 같은 키워드를 중첩해서 쓰는 전통적인 구조였다면,

Flat Config는 말 그대로 하나의 배열 안에 모든 설정 객체를 나열하는 구조로 바뀐 것이다.

 

구체적인 예시로는 예전에는 이러한 방식이었다면,

// .eslintrc.js (이전 방식)
module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
  ],
};

 

Flat Config에서는 이처럼 쓴다고 보면 된다.

// eslint.config.js (Flat Config)
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
import { defineConfig } from 'eslint/config';

export default defineConfig(
  eslint.configs.recommended,
  tseslint.configs.recommended,
);

 

 

예전보다 훨씬 직관적이고 코드 친화적으로 바뀐 것 같긴 하지만,

문제는 이러한 변화가 생기면서 많은 개발자들이 헷갈려하기 시작했다고 한다 🤣

 

특히 Flat Config가 처음 나왔을 때 사용자들의 피드백은 다음과 같았다고 한다.

• TS와 함께 쓰기 불편하다.
  👉🏻 flat config 구조에서 TS 관련 설정이 너무 복잡하게 느껴졌다고 한다.
• 다른 설정(config)을 가져와서 확장하기 어렵다.
  👉🏻 plugin마다 config를 내보내는 방식이 제각각이라 '이걸 어떻게 합치지?'라는 혼란이 많았다고 한다.
• ignores가 헷갈린다.
  👉🏻 어떤 경우에는 전역 ignore처럼, 어떤 경우에는 부분 ignore 처럼 동작했다고 한다.

 

그래서 위와 같은 피드백을 바탕으로 ESLint 팀은 크게 아래의 세 가지 기능을 개선했다고 한다.

• defineConfig( ) 도입 👉🏻 설정을 타입 안전하게 묶는 헬퍼
• extends 부활 👉🏻 이전처럼 설정 확장이 가능하도록 복귀
• globalIgnores( ) 도입 👉🏻 전역 무시 패턴을 명확히 구분

 

이러한 세 가지 개선점을 보며 flat config를 사용하더라도

기존 .eslintrc의 익숙함을 유지하는 것이 이번 변화의 핵심이지 않을까 생각했다.

 

 

---

🟩 Vite 템플릿이 만들어준 기본 ESLint 설정 뜯어보기

Vite로 React + TypeScript 프로젝트를 생성하면,

아래와 같이 eslint.config.js 파일이 자동으로 생성된다.

import js from '@eslint/js'
import globals from 'globals'
import reactHooks from 'eslint-plugin-react-hooks'
import reactRefresh from 'eslint-plugin-react-refresh'
import tseslint from 'typescript-eslint'
import { defineConfig, globalIgnores } from 'eslint/config'

export default defineConfig([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}'],
    extends: [
      js.configs.recommended,
      tseslint.configs.recommended,
      reactHooks.configs['recommended-latest'],
      reactRefresh.configs.vite,
    ],
    languageOptions: {
      ecmaVersion: 2020,
      globals: globals.browser,
    },
  },
])

 

지금까지의 내용을 바탕으로 위 설정을 한 줄씩 뜯어보면,

flat config + typescript-eslint + React 생태계가 어떻게 얽혀서 돌아가는지 잘 보일 것이다.

 

 

1. defineConfig + 배열 구조 👉🏻 flat config의 기본 틀

export default defineConfig([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}'],
    // ...
  },
])

 

이 부분을 보면, ESLint v9에서 도입된 flat config를 타입 안전하게 작성하기 위한 공식 헬퍼인 defineConfig가 있고,

인자로 설정 객체들의 배열을 넘기는 것을 볼 수 있다.

그리고, 이 배열의 각 요소가 어떤 파일에 어떤 규칙을 적용할지를 정의한다고 보면 된다.

 

위 설정 코드에서는 크기 두 가지 설정 블럭이 있는데,

glabolIgnores(['dist'])는 전역 ignore 설정이고,

{ files: ['**/*.{ts, tsx}'], ... }는 TypeScript와 TSX 파일에 적용할 실제 롤 세트이다.

 

이렇게 설정함으로써 dist 폴더는 ESLint 검사 대상에서 아예 빠지게 된다.

 

참고로, 실제 프로젝트에서는 보통 아래와 같이 확장해서 쓰는 경우도 많다고 한다.

globalIgnores(['dist', 'node_modules']),

 

어차피 node_modules도 외부 라이브러리 코드들이라

굳이 린트 대상으로 삼을 필요가 없기 때문이다.

 

 

2. extends 👉🏻 여러 추천 설정을 한 번에 덧씌우기

extends: [
  js.configs.recommended,
  tseslint.configs.recommended,
  reactHooks.configs['recommended-latest'],
  reactRefresh.configs.vite,
],

 

여기가 위 설정 코드의 핵심이라고 보면 된다.

 

한 줄씩 살펴보면,

js.configs.recommended

 

이 부분은 @eslint/js 패키지가 제공하는 기본적인 JS 추천 규칙 세트로,

JS 전반에서 '이 정도는 지키자' 수준의 룰들이 모여 있다고 보면 된다.

 

다음으로,

tseslint.configs.recommended

 

 

이 부분은 위에서 말했듯이 TS 전용 추천 규칙 세트이다.

이 설정을 통해서 TS 문법을 이해하는 parser와 plugin이 같이 활성화 되고,

TS 타입 관련 룰들 (ex. @typescript-eslint/no-unused-vars 등)이 켜진다.

 

그 다음으로,

reactHooks.configs['recommended-latest']

 

이 부분은 eslint-plugin-react-hooks에서 제공하는 React Hooks 전용 규칙 세트로,

이 설정 덕분에 useEffect 의존성을 빠뜨리거나,

useState를 조건문 안에서 호출하려는 실수 등을 자동으로 잡아줄 수 있게 된다.

 

마지막으로,

reactRefresh.configs.vite

 

이 부분은 eslint-plugin-react-refresh의 Vite용 설정으로,

React Fast Refresh(핫 리로드)와 관련된 제약을 체크해준다고 한다.

(이 부분은 뭔지 아직 잘 모르겠어서 추후 공부하고 다시 포스팅 할 예정이다.)

 

 

3. languageOptions 👉🏻 JS 문법 버전 + 브라우저 전역 변수

위의 설정 파일 중 이 부분을 살펴보자.

languageOptions: {
  ecmaVersion: 2020,
  globals: globals.browser,
},

 

여기에서 첫 줄은 ESLint가 어느 버전의 JS 문법까지 이해할지를 지정하는 것이고,

두 번째 줄은 globals 패키지에서 가져온 브라우저 환경 전역 변수 세트를 활성화하는 것이다.

 

 

---

🟦 처음 던졌던 다섯 가지 질문의 답

이 글의 맨 처음에 아래의 다섯 가지를 중심으로 정리하겠다고 했었으니,

이제 포스팅만으로는 확 와닿지 않는 분들을 위해 깔끔하게 답을 정리해두고자 한다.

 

• 왜 @typescript-eslint/parser와 eslint-plugin 대신에 typescript-eslint 패키지 하나로 정리되었는가
  • 예전에는 TS 코드 해석을 담당하는 parser와 TS용 규칙 세트인 plugin을 따로 설치해야 했지만,
    이제는 이 둘이 통합된 typescript-eslint 패키지 하나로 모두 제공된다.
    👉🏻 즉, parser, plugin, configs 등 TS 관련 도구들을 한 번에 포함하는 통합 엔트리 포인트로 정리된 것이다.
  • 이렇게 정리한 이유는 어차피 예전처럼 parser와 plugin이 나뉘어 있던 구조에서도 어차피 이 둘을 항상 세트로 설치했기 때문에 굳이 분리해둘 필요가 없기 때문이다.
    게다가 parser와 plugin은 항상 같은 버전끼리 써야 정상적으로 작동하기 때문에 따로 설치하게 두면, 버전 불일치 및 설정 복잡도 등의 문제가 있었다고 한다.
    👉🏻 따라서 이러한 이유로 typescript-eslint 하나로 필요한 구성 요소를 통합 제공해서, 설치, 설정, 유지보수를 단순화한 것이다.
• 새로운 방식인 flat config가 어떤 개념인가
  • 기존의 .eslintrc가 YAML/JSON 기반의 중첩 구조였다면,
    flat config는 설정 객체들을 배열로 나열하는 코드 중심 구조이다.
  • 따라서 예전보다 더 명시적이고, 타입 친화적이며, eslint.config.js 파일에서 직접 JS로 설정을 작성할 수 있다.
    👉🏻 즉, 설정 파일도 하나의 모듈처럼 작성한다는 게 핵심이다.
• defineConfig가 하는 역할과, 예전의 tseslint.config( ... )와의 관계는 무엇인가
  • tseslint.config( )는 한 때 typescript-eslint에서 제공하던 flat config 헬퍼 함수였다.
    즉, 여러 설정 객체를 합치고 타입 지원을 제공하는 역할을 했었다.
  • 그러나 ESLint v9부터는 같은 기능을 하는 defineConfig( )가 ESLint 코어에 공식 포함되었다.
  • 따라서 지금은 defineConfig( )를 쓰는 것이 표준이며,
    tseslint.config( )는 더 이상 권장되지 않는 deprecated 상태이다.
• flat config에서 다시 돌아온 extends의 의미와 사용 패턴은 무엇인가
  • flat config 초기에는 extends가 없어졌었지만,
    사용자들이 다른 설정을 가져와서 확장하기가 너무 어렵다고 피드백하면서 다시 돌아오게 되었다.
  • 따라서 이제는 extends 배열 안에 문자열(ex. "esling:recommended"), 객체(ex. { reles: { ... } } ), 배열 (ex. tseslint.configs.recommended, react.configs.flat)을 모두 넣을 수 있다.
    👉🏻 즉, 여러 설정들을 한 번에 겹쳐 덧씌우는 구조로 다시 정리된 것이다.
• .eslintignore 대신 설정 파일 안에서 사용하는 galobalIgnores란 무엇인가
  • flat config에서는 ignores가 전역, 로컬 두 가지 방식으로 혼용되어서 헷갈렸다.
    따라서 ESLint v9에서는 .eslintignore 역할을 대신하는 전역 무시용 함수인 globalIgnores( )가 추가된 것이다.
  • 이를 통해서 빌드 결과물(dist)이나 외부 라이브러리(node_modules) 등을 설정 파일 안에서 직접 전역적으로 제외할 수 있게 되었다.

 

 

---

📚 결론

ESLint v9는 더 타입 안전하고, 더 명시적인 구조로 가기 위해서 flat config 체계를 중심으로 많은 변화가 있던 것 같다.

typescript-eslint 통합 패키지와 defineConfig, extends, globalIgnores 같은 새로운 키워드들은
그 변화 속에서 개발자 경험을 단순화하고 일관성 있게 만든 결과물로 느껴졌다.

 

이번 포스팅을 통해서 새로운 ESLint 생태계가 왜 이렇게 바뀐 것인지,

어떤 코드 패턴이 현재 표준인지 감이 잡힌 것 같다.

 

앞으로도 공식 문서를 읽어보는 습관을 들여야겠다 ,,🤧