tsconfig.json 설정

타입스크립트 프로젝트의 핵심은 tsconfig.json입니다.

이 파일에는 컴파일러(tsc)의 컴파일 방식과 타입 검사 기준이 모두 담깁니다.

tsconfig.json이 없으면 기본 설정에 의존하거나, 명령줄 옵션을 매번 직접 입력해야 해 작업 효율이 크게 떨어집니다.

tsconfig.json 파일은 프로젝트의 규모, 목적, 사용 환경(Node.js, 브라우저, 특정 프레임워크 등)에 따라 매우 다양한 옵션을 가질 수 있습니다.

이 절에서는 가장 중요하고 자주 사용되는 tsconfig.json의 주요 설정들을 자세히 살펴보겠습니다.

tsconfig.json의 기본 구조

tsconfig.json 파일은 JSON 형식으로 작성되며, 최상위 속성으로 compilerOptions, files, include, exclude, extends 등을 가집니다.

{
  "compilerOptions": {
    // 컴파일러 옵션들을 여기에 정의
    "target": "es2018",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": [
    // 컴파일에 포함할 파일 또는 디렉토리 패턴
    "src/**/*"
  ],
  "exclude": [
    // 컴파일에서 제외할 파일 또는 디렉토리 패턴
    "node_modules",
    "dist"
  ],
  "files": [
    // 특정 파일을 명시적으로 포함 (거의 사용되지 않음)
    // "src/main.ts"
  ],
  "extends": "./configs/base.json" // 다른 tsconfig 파일을 상속
}

설정 모양과 실행 가능한 프로젝트를 구분합니다. 위 예시의 extends를 사용하려면 configs/base.json이 실제로 있어야 합니다. files: []는 명시적으로 추가한 시작 파일이 없다는 뜻이며, 함께 적힌 include까지 비우지는 않습니다. 다만 상속이나 참조가 없는 단일 설정에 빈 files: []를 두면 타입스크립트 6.0에서 TS18002 진단이 나올 수 있습니다. 일반 단일 프로젝트는 실제 파일명을 적거나 files 항목을 생략하고 include를 사용하세요. 설정 파일을 만들었다는 사실만으로 편집기·빌드 도구·런타임이 모두 같은 설정을 사용한다고 단정하지 말고, 다음 절의 tsc -p로 선택한 프로젝트를 확인합니다.

주요 compilerOptions

compilerOptions는 tsconfig.json에서 가장 중요한 부분으로, 타입스크립트 컴파일러의 동작 방식을 제어하는 수많은 옵션들을 포함합니다.

파일 포함 및 제외 옵션

• include: 컴파일러가 타입 검사를 수행하고 컴파일할 파일이나 디렉터리 패턴(glob 패턴)의 배열을 지정합니다. rootDir와 함께 사용될 때 효과적입니다.
  • 예시: "include": ["src/**/*.ts", "tests/**/*.ts"]
• exclude: include에 의해 포함될 수 있는 파일이라도 컴파일에서 제외할 파일이나 디렉터리 패턴의 배열을 지정합니다. node_modules와 컴파일 출력 디렉터리는 기본적으로 제외됩니다.
  • 예시: "exclude": ["node_modules", "dist", "**/*.spec.ts"]
• files: 컴파일할 특정 파일들의 목록을 배열로 직접 지정합니다. 소규모 프로젝트에서만 사용되며, 일반적으로 include를 선호합니다.

exclude는 include의 검색 결과를 제한할 뿐 import된 파일이나 files에 명시된 파일까지 차단하지 않습니다. rootDir도 포함 파일을 고르는 옵션이 아니라 출력 경로와 emit 범위를 제약합니다.

extends (설정 상속)

extends 속성을 사용하면 다른 tsconfig.json 파일의 설정을 상속받을 수 있습니다.

이는 여러 프로젝트나 모듈 간에 공통된 설정을 공유하고, 특정 설정을 오버라이드할 때 유용합니다.

{
  "compilerOptions": {
    "target": "es2020",
    "module": "esnext",
    "strict": true,
    "esModuleInterop": true
  }
}

{
  "extends": "./configs/base.json", // base.json 설정을 상속
  "compilerOptions": {
    "outDir": "./dist",
    "declaration": true // base.json에는 없는 추가 옵션
  },
  "include": [
    "src/**/*.ts"
  ]
}

extends는 기본 설정을 읽은 뒤 현재 옵션을 덮어씁니다. files·include·exclude는 자식에 있으면 기본 배열을 대체하며 references는 상속하지 않습니다. 상대 경로는 그 설정을 작성한 파일을 기준으로 해석합니다.

주석 사용

tsconfig.json은 주석과 후행 쉼표를 허용하는 JSONC 방식으로 작성할 수 있습니다. 모든 JSON5 문법을 지원한다는 뜻은 아닙니다.

이는 설정의 목적을 설명하고 다른 개발자들이 이해하기 쉽게 만드는 데 도움이 됩니다.

{
  "compilerOptions": {
    "target": "es2020", // 최신 ECMAScript 문법 지원
    "module": "esnext", // ES 모듈 시스템 사용
    "strict": true       /* 모든 엄격한 타입 검사 활성화 */
  }
}

tsconfig.json 파일은 타입스크립트 프로젝트의 컴파일과 타입 검사 동작을 제어하는 중심점입니다.

프로젝트 요구사항과 개발 환경에 맞춰 이 파일의 옵션을 신중하게 설정하는 것이 매우 중요합니다.

설정을 바꿀 때는 문법 출력, 모듈 해석, 타입 엄격성, 산출물의 영향을 한 번에 점검해야 예상치 못한 빌드 변화를 줄일 수 있습니다.

특히 target, module, strict, esModuleInterop, jsx, moduleResolution, baseUrl, paths 옵션은 프로젝트 구조와 런타임 동작에 큰 영향을 미치므로 충분히 이해하고 사용해야 합니다.

다음 절에서는 타입스크립트 컴파일러 tsc를 직접 실행하고 사용하는 방법에 대해 알아보겠습니다.

target은 문법 출력과 기본 lib 선택에 영향을 주지만 polyfill을 설치하지 않습니다. lib와 paths도 런타임 API나 import 경로를 자동으로 구현·변환하지 않습니다. 위 ES3와 node/classic 표기는 과거 선택지를 포함하므로 설치한 TypeScript 버전에 맞춰야 하며, 현대 Node ESM은 node16/nodenext 계열의 module·resolution 조합을 확인합니다.

아래 다이어그램은 tsconfig.json의 기본 구조와 주요 compilerOptions가 타입 해석과 빌드 결과에 주는 영향을 정리합니다.

버전이 바뀌면 선택지와 기본값도 달라집니다. 위 목록은 과거 TypeScript의 선택지도 함께 설명합니다. 예를 들어 TypeScript 6.0에서는 baseUrl과 moduleResolution: "node"가 폐기 예정 옵션이며, 프로젝트에 맞는 현대 설정을 선택하는 것이 우선입니다. paths에 baseUrl이 반드시 필요한 것은 아니며(TypeScript 4.1 이후), paths만 지정하면 해당 설정 파일 위치를 기준으로 상대 경로를 해석할 수 있습니다. 설치 버전과 런타임을 확인한 뒤 설정을 선택하고, 오래된 예시의 옵션을 그대로 복사해 모든 버전에서 동작한다고 기대하지 않습니다.

파일 선택을 작은 프로젝트로 추적해 봅니다. 다음 사례는 TypeScript 4.7 이상의 Node16 옵션 조합을 사용합니다. 프로젝트 안에 아래 세 파일과 tsconfig.json만 있으며, package.json은 없다고 가정합니다. types: []는 주변의 자동 포함 @types 패키지가 이 사례에 끼어들지 않게 하는 조건입니다.

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "Node16",
    "moduleResolution": "Node16",
    "strict": true,
    "rootDir": "./src",
    "outDir": "./dist",
    "types": [],
    "noEmitOnError": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["src/secret.ts", "**/*.spec.ts"]
}

import { amount } from "./secret";
export const total = amount + 1;

export const amount: number = 2;

const value: number = "bad";

tsc -p .를 실행할 때, 표준 라이브러리 선언 파일을 제외한 프로젝트 파일만 세어 다음을 설명해 보세요.

1. include·exclude 검색으로 고른 시작 파일과, import를 따라 완성한 프로그램의 파일은 각각 무엇인가요? unused.spec.ts의 타입 오류도 진단하나요?
2. 처음 상태에서 어떤 JavaScript 파일을 출력하며, total을 계산한 값은 얼마인가요? 선언 파일도 자동으로 나오나요?
3. secret.ts만 export const amount: number = "two";로 바꾸고 기존 dist가 없는 새 작업 폴더에서 다시 컴파일하면, 이 파일은 exclude되어 있으므로 오류와 출력에 영향을 주지 않을까요?