TypeScript ESLint — 타입 인식 린팅 완전 가이드

지난 글에서 Prettier와 ESLint의 역할을 분리하는 방법을 다뤘습니다. 이번에는 TypeScript 코드를 위한 ESLint 설정, 즉 @typescript-eslint 패키지 생태계를 깊이 살펴봅니다. 일반 ESLint 규칙은 TypeScript 타입 정보를 모릅니다. 예를 들어 Promise를 반환하는 함수를 await 없이 호출해도 기본 규칙은 침묵합니다. TypeScript ESLint는 TypeScript 컴파일러의 타입 체커(Type Checker)를 ESLint 규칙 안으로 끌어들여 이 공백을 메웁니다.

아키텍처 개요

TypeScript ESLint 아키텍처

TypeScript ESLint는 크게 두 패키지로 나뉩니다.

@typescript-eslint/parser — ESLint가 .ts/.tsx 파일을 파싱할 수 있도록 TypeScript 컴파일러 API를 이용해 TSESTree 형식의 AST를 생성합니다. 선택적으로 TypeScript Program 객체(타입 정보 포함)도 넘겨줍니다.
@typescript-eslint/eslint-plugin — TSESTree + 타입 정보를 활용하는 규칙 100개 이상을 제공합니다. 타입 정보를 요구하는 규칙은 parserOptions.project가 설정되어야 동작합니다.

typescript-eslint 패키지는 위 두 패키지를 묶어서 더 편리한 API(tseslint.config())와 사전 구성된 config 객체를 제공합니다.

설치

# 최신 통합 패키지 (권장)
npm install -D typescript-eslint

# 또는 개별 패키지
npm install -D @typescript-eslint/parser @typescript-eslint/eslint-plugin

TypeScript 자체와 ESLint 9+ 가 이미 설치되어 있어야 합니다.

npm install -D eslint typescript

기본 설정 (Flat Config)

// eslint.config.mjs
import tseslint from 'typescript-eslint'

export default tseslint.config(
  // 타입 정보 없이 동작하는 기본 규칙
  ...tseslint.configs.recommended,
)

타입 인식 규칙까지 활성화하려면 recommendedTypeChecked를 쓰고 parserOptions.project를 설정합니다.

// eslint.config.mjs
import tseslint from 'typescript-eslint'

export default tseslint.config(
  ...tseslint.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        project: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
)

project: true는 각 파일에서 가장 가까운 tsconfig.json을 자동으로 찾습니다.

설정 단계와 강도

typescript-eslint 설정 레시피

프리셋	타입 정보 필요	설명
`recommended`	❌	기본 품질 규칙, CI 첫 도입에 적합
`recommendedTypeChecked`	✅	타입 인식 규칙 포함, 대부분의 프로젝트 권장
`strict`	✅	`recommended` + 더 엄격한 규칙
`strictTypeChecked`	✅	가장 엄격한 세트
`stylistic`	❌	코드 스타일(일관성) 규칙
`stylisticTypeChecked`	✅	타입 인식 스타일 규칙

주요 타입 인식 규칙

`@typescript-eslint/no-floating-promises`

Promise를 반환하는 함수 호출에서 await 또는 .catch()가 없으면 오류를 냅니다. 런타임에서 조용히 실패하는 비동기 코드의 가장 흔한 버그를 잡아냅니다.

// 오류: fetchData()가 Promise를 반환하지만 await 없음
fetchData()

// 정상
await fetchData()
fetchData().catch(console.error)

// 결과를 쓰지 않는다는 명시적 표시
void fetchData()

`@typescript-eslint/no-unsafe-assignment`

any 타입의 값을 다른 변수에 할당할 때 경고합니다. any가 코드베이스 전체로 전파되는 것을 막습니다.

const data: any = getExternalData()
const name = data.name   // 오류: any 할당
const name2: string = data.name  // 오류: 여전히 any

// 해결: 런타임 검증 후 타입 단언
if (typeof data.name === 'string') {
  const name3 = data.name  // string으로 좁혀짐
}

`@typescript-eslint/consistent-type-imports`

타입 전용 import에 import type을 강제합니다. 번들러 tree-shaking과 isolatedModules 모드에서 중요합니다.

// 오류
import { User, createUser } from './user'

// 정상
import type { User } from './user'
import { createUser } from './user'

// 또는 인라인 type
import { type User, createUser } from './user'

`@typescript-eslint/await-thenable`

await 뒤에 Promise가 아닌 값이 오면 경고합니다.

const value = 42
await value   // 오류: number는 Thenable이 아님

JS 파일 처리

TypeScript ESLint 규칙 중 일부는 .js 파일에서도 사용할 수 있습니다. allowJs: true가 tsconfig.json에 있으면 JS 파일도 타입 체킹 대상이 됩니다.

// eslint.config.mjs
export default tseslint.config(
  {
    files: ['**/*.ts', '**/*.tsx'],
    extends: [...tseslint.configs.recommendedTypeChecked],
    languageOptions: {
      parserOptions: { project: true, tsconfigRootDir: import.meta.dirname },
    },
  },
  {
    // JS 파일은 타입 정보 없는 세트만 적용
    files: ['**/*.js', '**/*.mjs'],
    extends: [...tseslint.configs.recommended],
  },
)

성능: `parserOptions.project`의 비용

타입 인식 규칙은 TypeScript 컴파일러를 내부적으로 실행하므로 린팅 속도가 크게 느려집니다. 대형 모노레포에서는 project를 세분화하거나 projectService 옵션을 사용하는 것이 좋습니다.

// 성능 최적화: projectService 사용 (v6+)
languageOptions: {
  parserOptions: {
    projectService: true,
    tsconfigRootDir: import.meta.dirname,
  },
}

projectService는 파일별로 필요한 tsconfig만 로드해 메모리와 시간을 줄입니다.

단계적 마이그레이션 전략

기존 JS 프로젝트를 TS로 마이그레이션하는 경우, 처음부터 strict를 적용하면 수백 개의 오류가 발생합니다. 단계적으로 올리는 것이 현실적입니다.

// 1단계: warn으로 시작
rules: {
  '@typescript-eslint/no-explicit-any': 'warn',
  '@typescript-eslint/no-unsafe-assignment': 'warn',
}

// 2단계: 오류 수 줄인 후 error로 전환
rules: {
  '@typescript-eslint/no-explicit-any': 'error',
  '@typescript-eslint/no-unsafe-assignment': 'error',
}

React + TypeScript 조합

// eslint.config.mjs
import tseslint from 'typescript-eslint'
import react from 'eslint-plugin-react'
import reactHooks from 'eslint-plugin-react-hooks'

export default tseslint.config(
  ...tseslint.configs.recommendedTypeChecked,
  {
    plugins: { react, 'react-hooks': reactHooks },
    rules: {
      ...react.configs.recommended.rules,
      ...reactHooks.configs.recommended.rules,
    },
    settings: { react: { version: 'detect' } },
    languageOptions: {
      parserOptions: { project: true, tsconfigRootDir: import.meta.dirname },
    },
  },
)

지난 글: Prettier와 ESLint 역할 분리 — 포맷터와 린터 공존

다음 글: Husky + lint-staged — 커밋 훅으로 품질 게이트 구축

읽어주셔서 감사합니다. 😊