tsconfig.json 설정

타입스크립트 프로젝트의 핵심은 tsconfig.json입니다. 이 파일에는 컴파일러(tsc)의 컴파일 방식과 타입 검사 기준이 모두 담깁니다.

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

tsconfig.json 파일은 프로젝트의 규모, 목적, 사용 환경(Node.js, 브라우저, 특정 프레임워크 등)에 따라 매우 다양한 옵션을 가질 수 있습니다. 이 절에서는 가장 중요하고 자주 사용되는 tsconfig.json의 주요 설정들을 자세히 살펴보겠습니다.

`tsconfig.json`의 기본 구조

tsconfig.json 설정에서 타입 경계, 추론 결과, 런타임 영향을 정리한 것입니다.

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

tsconfig.json

{
  "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 파일을 상속
}

주요 `compilerOptions`

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

target (ECMAScript 대상 버전)

생성될 JavaScript 코드의 ECMAScript 버전을 지정합니다. 구형 브라우저나 Node.js 버전을 지원해야 한다면 낮은 버전을, 최신 환경이라면 높은 버전을 설정합니다.
값: "ES3", "ES5", "ES2015" (또는 "ES6"), "ES2016", "ES2017", "ES2018", "ES2019", "ES2020", "ES2021", "ES2022", "ESNext"
예시: "target": "es5" (구형 브라우저 지원), "target": "es2020" (최신 문법 사용), "target": "esnext" (사용 가능한 최신 문법)

module (모듈 시스템) (7.1, 7장 2절 참조)

생성될 JavaScript 코드의 모듈 형식을 지정합니다.
값: "commonjs", "amd", "umd", "system", "es2015", "es2020", "esnext", "node16", "nodenext"
예시: "module": "commonjs" (Node.js 백엔드), "module": "esnext" (프론트엔드 + 번들러)

lib (라이브러리 선언 파일)

컴파일 시 포함할 표준 내장 API 정의 파일(.d.ts 파일) 목록을 지정합니다. 특정 전역 API(DOM, ES2015 Collections 등)를 사용하려면 명시해야 합니다.
값: "dom", "es2015", "es2016.array.include", "webworker", "scripthost" 등.
예시: "lib": ["es2020", "dom"] (ES2020 문법과 브라우저 DOM API 사용)
팁: target에 따라 일부 lib가 자동으로 포함됩니다 (예: target: "es2015"는 lib: ["es2015", "dom"]을 암시).

outDir (출력 디렉토리)

컴파일된 JavaScript 파일(.js)과 타입 정의 파일(.d.ts)이 생성될 출력 디렉토리 경로를 지정합니다.
예시: "outDir": "./dist"

rootDir (루트 디렉토리)

프로젝트의 소스 파일이 위치한 루트 디렉토리를 지정합니다. 이 경로를 기준으로 outDir로의 출력 경로가 결정됩니다.
예시: "rootDir": "./src"

strict (엄격 모드 활성화)

타입스크립트의 모든 엄격한 타입 검사 옵션(noImplicitAny, strictNullChecks, strictFunctionTypes 등)을 한 번에 활성화/비활성화합니다. true로 설정하는 것이 강력히 권장됩니다.
값: true | false
예시: "strict": true

esModuleInterop (CommonJS-ESM 호환성) (7장 2절 참조)

CommonJS 모듈의 export와 ES 모듈의 import 구문 간의 상호 운용성을 향상시킵니다. Node.js 환경에서 ES 모듈처럼 import 구문을 사용할 때 유용하며, true로 설정하는 것이 일반적입니다.
값: true | false
예시: "esModuleInterop": true

skipLibCheck (라이브러리 타입 검사 건너뛰기)

선언 파일(.d.ts 파일, 특히 node_modules 내부의 파일)에 대한 타입 검사를 건너뛸지 여부를 지정합니다. 대규모 프로젝트의 컴파일 시간을 단축하거나, 간혹 잘못된 @types 정의로 인해 발생하는 오류를 무시할 때 사용될 수 있습니다. 일반적으로 true로 설정하는 것이 좋습니다.
값: true | false
예시: "skipLibCheck": true

forceConsistentCasingInFileNames (파일 이름 대소문자 일관성)

파일 이름의 대소문자가 일관되지 않을 경우 오류를 발생시킬지 여부를 지정합니다. Windows와 macOS는 파일 시스템이 대소문자를 구분하지 않을 수 있지만, Linux는 구분하기 때문에 플랫폼 간의 문제를 방지하는 데 도움이 됩니다. true로 설정하는 것이 권장됩니다.
값: true | false
예시: "forceConsistentCasingInFileNames": true

declaration (타입 정의 파일 생성) (8장 2절 참조)

타입스크립트 소스 파일과 함께 해당 타입 정의 파일(.d.ts 파일)을 생성할지 여부를 지정합니다. 라이브러리를 배포할 때 필수적입니다.
값: true | false
예시: "declaration": true

jsx (JSX 처리 방식)

JSX 구문을 어떻게 처리할지 지정합니다. React나 Preact와 같은 UI 프레임워크를 사용할 때 필수적입니다.
값: "preserve", "react", "react-jsx", "react-jsxdev", "react-native"
예시: "jsx": "react-jsx" (React 17+ 권장)

moduleResolution (모듈 해석 전략) (7장 4절 참조)

import 문에서 모듈을 찾아내는 전략을 지정합니다.
값: "node", "bundler", "classic"
예시: "moduleResolution": "node" (Node.js 환경), "moduleResolution": "bundler" (모던 번들러 사용 시)

baseUrl 및 paths (절대 경로 및 별칭) (7장 4절 참조)

baseUrl: 비-상대 모듈 임포트의 기준 디렉토리를 지정합니다.
paths: baseUrl을 기준으로 모듈 가져오기 경로에 대한 별칭 매핑을 정의합니다.

예시

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

sourceMap (소스 맵 생성)

컴파일된 JavaScript 파일과 원본 TypeScript 소스 파일 간의 매핑 정보를 담은 소스 맵 파일(.map 파일)을 생성할지 여부를 지정합니다. 디버깅에 필수적입니다.
값: true | false
예시: "sourceMap": true

파일 포함 및 제외 옵션

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

아래 다이어그램은 files, include, exclude가 최종 타입 검사 대상 파일 집합을 만드는 흐름을 보여줍니다.

`extends` (설정 상속)

extends 속성을 사용하면 다른 tsconfig.json 파일의 설정을 상속받을 수 있습니다. 이는 여러 프로젝트나 모듈 간에 공통된 설정을 공유하고, 특정 설정을 오버라이드할 때 유용합니다.

configs/base.json (기본 설정)

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

tsconfig.json (프로젝트의 실제 설정)

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

extends를 사용하면 base.json의 모든 설정이 적용되고, 현재 파일의 compilerOptions는 이를 덮어쓰거나 새로운 옵션을 추가합니다.

주석 사용

tsconfig.json 파일은 JSON5 형식을 지원하여 주석(// 또는 /* */)을 사용할 수 있습니다. 이는 설정의 목적을 설명하고 다른 개발자들이 이해하기 쉽게 만드는 데 도움이 됩니다.

tsconfig.json

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

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

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

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

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

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

다음 다이어그램은 tsconfig.json 설정을 검사 범위와 컴파일 옵션 기준으로 정리한 표입니다.

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

아래 다이어그램은 tsconfig.json 설정에서 설정 위치, 타입 해석, 빌드 실패 신호를 확인합니다.

아래 다이어그램은 tsconfig.json 설정을 마무리하며 설정 파일, 타입 해석 범위, 빌드 결과를 한 번 더 확인합니다.

tsconfig.json의 기본 구조

주요 compilerOptions

파일 포함 및 제외 옵션

extends (설정 상속)

주석 사용

목차

`tsconfig.json`의 기본 구조

주요 `compilerOptions`

`extends` (설정 상속)