[Frontend] ESLint v9로 TS+React 린팅 환경 만들기

목차 (OPEN)

• 📑 들어가며
• 🟥 환경
• 🟧 최종 설정 파일
• 🟨 설정 설명
• 📚 결론

 

 

 

 

📑 들어가며

지난 포스팅에서 ESLint v9 공식 문서를 살펴봤으니,

이번 포스팅에서는 내가 실제 프로젝트에서 적용하려고 설정한 eslint.config.js를 바탕으로

왜 이렇게 설정을 했는지, 각 옵션이 어떤 역할을 하는지를 정리해보려 한다.

 

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

 

 

---

🟥 환경

• 스택: Vite + React + TypeScript
• ESLint: v9 (Flat Config 기반)

 

 

---

🟧 최종 설정 파일

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

export default defineConfig([
  // 1) 린팅 범위 최소화
  globalIgnores(['dist', 'node_modules']),

  // 2) React + TS 파일에만 룰 적용
  {
    files: ['**/*.{ts,tsx}'],
    // d.ts는 타입 선언 파일이라 규칙 적용 대상에서 제외
    ignores: ['**/*.d.ts'],

    // 3) 추천 규칙 세트 확장
    extends: [
      js.configs.recommended,
      ...tseslint.configs.recommended,          // TS 추천 룰(배열이라 전개)
      reactPlugin.configs.flat.recommended,     // React 기본 권장
      reactHooks.configs['recommended-latest'], // Hooks 규칙
      reactRefresh.configs.vite,                // Vite + Fast Refresh 제약
    ],

    // 4) 코드 이해 능력 상향 (TS 문법/타입 인지)
    languageOptions: {
      ecmaVersion: 2020,
      sourceType: 'module',        // import/export 구문 인식
      parser: tseslint.parser,     // TS 문법 파싱
      parserOptions: { projectService: true },  // TSConfig 기반의 타입 인지 룰 ON
      globals: { ...globals.browser },          // window, document 등 전역 식별자 인식
    },

    // 5) React 버전 인지 (룰 동작이 버전에 따라 달라짐)
    settings: {
      react: { version: 'detect' },
    },

    // 6) 커스텀 룰
    rules: {
      // 운영 배포 시 남기고 싶은 콘솔만 허용
      'no-console': ['warn', { allow: ['warn', 'error'] }],
      'no-debugger': 'error',
      
      // React 17+ 부터는 import React 생략 가능하므로 비활성화
      'react/react-in-jsx-scope': 'off',

      // TS로 PropTypes 대체
      'react/prop-types': 'off',

      // 미사용 변수 잡되, 의도적 미사용(_prefix)은 허용
      '@typescript-eslint/no-unused-vars': [
        'warn',
        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
      ],
      // any 남발 방지 (팀 상황 따라 'error'로 격상 가능)
      '@typescript-eslint/no-explicit-any': 'warn',
    },
  },
])

 

결론부터 말하자면, 위와 같이 설정함으로써

검사 범위를 줄여서 속도를 확보하고, ESLint가 TS 타입 정보까지 인지해서 규칙을 더 정확히 적용하도록 해주었다.

 

 

---

🟨 설정 설명

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

ESLint가 검사하지 않아도 되는 폴더를 지정해준다.

보통 빌드 결과물(dist)과 외부 라이브러리(node_modules)는 자동 생성된 코드이므로

린트할 필요가 없어서 제외해주었다.

 

 

2. extends

어떤 규칙 세트를 기반으로 검사할지를 정해주는 것으로,

내 설정에 사용된 각각의 의미는 다음과 같다.

 

설정	설명
js.configs.recommended	자바스크립트 기본 권장 규칙
tseslint.configs.recommended	타입스크립트 문법 + 타입 기반 규칙
reactPlugin.configs.flat.recommended	React 전용 규칙
reactHooks.configs['recommended-latest']	useEffect, useState 같은 훅 관련 규칙
reactRefresh.configs.vite	Vite의 Fast Refresh 안정성 체크용

 

 

3. languageOptions

ESLint가 코드를 어떤 문법과 환경으로 이해할지를 설정해준다.

아래와 같이 설정해줌으로써, ESLint가 'TypeScript를 사용하는 브라우저 기반 프로젝트'임을 이해할 수 있게 해주었다.

키	역할
ecmaVersion: 2020	최신 JS 문법 지원
sourceType: 'module'	import/export 구문 사용 허용
parser: tseslint.parser	TS 문법 해석 (기본 ESLint는 TS 모름)
parserOptions.projectService: true	TS 타입 정보 기반 규칙 활성화
globals.browser	window, document 등 브라우저 전역 식별자 인식

 

 

4. settings.react.version: 'detect'

React 관련 규칙들은 버전에 따라 다르게 동작하기 때문에

버전을 자동으로 감지하게 해주는 옵션을 추가해주었다.

 

예를 들어, React 17 이후부터는 JSX를 사용할 때 import React from 'react'가 필요 없기 때문에
이 옵션이 없으면 불필요한 오류가 발생할 수도 있다고 한다.

 

 

5. rules

팀에서 자주 겪는 패턴을 직접 조정할 수 있는 것으로, 내가 사용한 규칙은 아래와 같다.

규칙	의미
no-console	개발용 로그는 허용, 배포용은 경고
no-debugger	배포 코드에서 디버거 금지
react/react-in-jsx-scope	React 17 이상에서는 JSX 사용 시 import React가 필요 없으므로 비활성화
react/prop-types	TypeScript 환경에서는 PropTypes 대신 TS 타입 사용
@typescript-eslint/no-unused-vars	사용하지 않는 변수 잡기 (단, _로 시작하면 무시)
@typescript-eslint/no-explicit-any	any 타입 사용 시 경고 (점진적 개선용)

 

 

---

📚 결론

내 설정의 핵심은 정확한 검사 + 빠른 속도 + 현실적인 규칙이었다.

 

globalIgnores로 검사 범위를 줄이고,

typescript-eslint로 타입 기반 규칙을 활성화 하며,

extends로 React / TS 전용 규칙을 한 번에 덧씌워주었다.

 

확실히 공식 문서를 한 번 꼼꼼히 본 후에 직접 설정을 작성하니까

그동안 남들이 작성해둔 설정을 가져와서 쓰면서

'갑자기 여기서는 에러가 왜 나는 거지 ..' 하는 상황이 줄어들 것 같다.