tsconfig.json 설정

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

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

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

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

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

입력
files / include
프로젝트에 들어올 소스 범위를 선택
제외
exclude
include로 잡힌 후보 중 불필요한 경로 제거
검사
strict
null·함수·속성 초기화 등 타입 안전성 강화
출력
target / module
실행 환경에 맞는 JavaScript 형태 결정

`tsconfig.json`의 기본 구조

files/include
files/include 컴파일 대상 범위
compilerOptions
compilerOptions target
module, strict 같은 검사 규칙
outDir/rootDir
outDir/rootDir 입력
출력 위치
extends
extends 공통 설정 재사용

기준	해석
strict	타입 안정성 기준을 높임
noEmit	검사만 수행하는 프로젝트에 사용
핵심	tsconfig는 빌드 도구가 아니라 타입 검사 경계의 지도다

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가 최종 타입 검사 대상 파일 집합을 만드는 흐름을 보여줍니다.

files가 있으면 정확히 지정
"files": ["src/main.ts"] 작은 샘플이나 설정 검증처럼 파일 수가 고정된 경우에 씁니다.
include로 후보 수집
"include": ["src/**/*.ts"] 일반 프로젝트에서는 소스와 테스트 패턴을 glob으로 모읍니다.
exclude로 산출물 제거
"exclude": ["dist"] 빌드 결과, 임시 파일, 생성 코드를 include 후보에서 제외합니다.

`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는 이를 덮어쓰거나 새로운 옵션을 추가합니다.

base
configs/base.json
base target, module, strict 같은 팀 공통 기준을 먼저 읽습니다.
project
tsconfig.json
project outDir, declaration, include처럼 프로젝트별 값을 추가합니다.
files
include / exclude
files 실제로 검사할 소스 집합은 최상위 파일 범위 옵션으로 결정됩니다.
compilerOptions
객체 안의 옵션은 상속값과 현재 값을 합쳐 최종 옵션 객체를 만듭니다.
files 범위
include, exclude, files는 프로젝트의 실제 검사 대상을 명확히 나눕니다.

주석 사용

tsconfig.json 파일은 JSON5 형식을 지원하여 주석(// 또는 /* */)을 사용할 수 있습니다.

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

tsconfig.json

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

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

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

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

target 와 lib
Runtime 실행 환경이 이해할 문법과 사용할 전역 API를 맞춥니다.
module 해석
Import Node, 번들러, ESM 정책에 맞춰 import 결과를 확인합니다.
strict 계열
Safety 느슨한 타입을 허용할지, 오류를 빨리 드러낼지 결정합니다.
outDir 산출물
컴파일 산출물 빌드 결과, 선언 파일, 소스 맵 위치가 배포 흐름과 맞는지 봅니다.

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

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

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

컴파일 규칙
compilerOptions target, module, strict처럼 타입 검사와 출력 방식을 정하는 핵심 영역입니다. compilerOptions
검사 대상
include 프로젝트에 포함할 소스 파일 패턴을 명시해 컴파일러의 입력 범위를 정합니다. include
제외 패턴
exclude 빌드 결과물이나 외부 폴더처럼 검사에서 뺄 경로를 정리합니다. exclude
설정 상속
extends 공통 설정을 기반으로 프로젝트별 차이만 덮어써 중복을 줄입니다. extends

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

base
공통 strict·target
조직 전체가 공유할 안전성·런타임 기준
extends
기본값 불러오기
상대 경로의 설정을 먼저 읽는다
override
패키지별 덮어쓰기
module·outDir 등 다른 값만 재정의
scope
include / exclude
설정이 소유할 실제 소스 집합 확정
result
tsc --showConfig
합쳐진 최종 계약을 눈으로 검증

tsconfig.json의 기본 구조

주요 compilerOptions

파일 포함 및 제외 옵션

extends (설정 상속)

주석 사용

이 페이지의 목차

`tsconfig.json`의 기본 구조

주요 `compilerOptions`

`extends` (설정 상속)