tsconfig — TypeScript 컴파일러 설정 파일

TypeScript 프로젝트에는 tsconfig.json 파일이 있습니다. 어떤 파일을 컴파일할지, 어떤 JavaScript 버전으로 변환할지, 얼마나 엄격하게 검사할지를 이 파일 하나로 제어합니다.

기본 구조

{
  "compilerOptions": {
    // 컴파일러 동작 옵션
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

include에 포함된 파일 중 exclude에 명시된 경로를 제외한 파일들을 컴파일합니다.

핵심 옵션

target

컴파일 결과물의 JavaScript 버전을 지정합니다.

{
  "compilerOptions": {
    "target": "ES2020"
  }
}

ES2015, ES2016, ES2017, ES2020, ES2022, ESNext 등을 쓸 수 있습니다. 지원해야 하는 환경 중 가장 낮은 버전을 기준으로 설정합니다.

module

모듈 시스템을 지정합니다.

{
  "compilerOptions": {
    "module": "NodeNext"  // Node.js
    // "module": "ESNext" // 번들러(Vite, Webpack 등)와 함께 쓸 때
  }
}

outDir / rootDir

컴파일 결과물 경로와 소스 파일 루트를 지정합니다.

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist"
  }
}

src/utils/math.ts → dist/utils/math.js로 같은 구조가 유지됩니다.

lib

사용할 내장 타입 선언 라이브러리를 지정합니다.

{
  "compilerOptions": {
    "lib": ["ES2020", "DOM"]
  }
}

DOM을 포함하면 브라우저 API(document, window, fetch 등)의 타입을 사용할 수 있습니다. Node.js 전용 프로젝트라면 DOM을 빼는 것이 정확합니다.

strict 모드

strict: true 하나로 여러 엄격한 검사를 한 번에 켭니다. 새 프로젝트라면 처음부터 켜는 것을 권장합니다.

{
  "compilerOptions": {
    "strict": true
  }
}

strict가 활성화하는 주요 옵션들입니다.

이 중 **strictNullChecks**는 가장 큰 영향을 미치는 옵션으로, null과 undefined를 별도 타입으로 취급해 런타임 오류를 사전에 차단합니다. 이 옵션 없이는 null과 undefined를 모든 타입에 할당할 수 있으며, strict 모드에서는 명시적으로 처리해야 합니다.

noImplicitAny

타입이 추론되지 않아 any로 처리되는 경우를 오류로 처리합니다.

// noImplicitAny가 켜져 있으면 오류
function greet(name) { // 오류: 'name'은 암묵적으로 'any' 타입입니다
  return "안녕, " + name;
}

// 명시적 어노테이션 추가
function greet(name: string) {
  return "안녕, " + name;
}

경로 별칭 설정

긴 상대 경로를 짧게 쓸 수 있습니다.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

// 변경 전
import { Button } from "../../../components/Button";

// 변경 후
import { Button } from "@components/Button";

경로 별칭은 TypeScript 컴파일러에게만 알리는 설정입니다. 번들러(Vite, Webpack 등)에도 같은 별칭을 따로 설정해야 합니다.

선언 파일 생성

라이브러리를 만들 때 .d.ts 파일을 자동 생성합니다.

{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,  // .d.ts.map 파일도 생성
    "declarationDir": "./types"
  }
}

자주 쓰는 추가 옵션

{
  "compilerOptions": {
    "esModuleInterop": true,        // CommonJS 모듈을 ES 모듈처럼 import
    "skipLibCheck": true,           // node_modules의 .d.ts 검사 생략 (빌드 속도 향상)
    "resolveJsonModule": true,      // .json 파일 import 허용
    "noUnusedLocals": true,         // 미사용 지역 변수 오류
    "noUnusedParameters": true,     // 미사용 매개변수 오류
    "noImplicitReturns": true,      // 모든 분기에서 반환값을 요구
    "exactOptionalPropertyTypes": true  // undefined와 선택적 프로퍼티를 구분
  }
}

설정 확장

공통 설정을 기반으로 환경별 설정을 만들 때 extends를 씁니다.

// tsconfig.base.json
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2020"
  }
}

// tsconfig.json (프로덕션)
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist"
  },
  "include": ["src"]
}

strict: true를 설정하고 시작하는 것이 나중에 엄격도를 높이는 것보다 훨씬 쉽습니다. 기존 JavaScript 코드베이스에 TypeScript를 도입할 때는 strict를 점진적으로 켜면서 오류를 하나씩 처리하는 방법을 씁니다.