icon
9장 : 타입스크립트 컴파일러

tsconfig.json 설정

타입스크립트 프로젝트의 핵심은 바로 tsconfig.json 파일입니다. 이 파일은 프로젝트의 루트 디렉토리에 위치하며, 타입스크립트 컴파일러(tsc)가 소스 코드를 컴파일하고 타입 검사를 수행하는 방법에 대한 모든 설정을 담고 있습니다. tsconfig.json 파일이 없으면 tsc 명령어를 실행할 때 기본 설정만 적용되거나, 명령줄 옵션으로 모든 설정을 일일이 지정해야 하므로 매우 비효율적입니다.

tsconfig.json 파일은 프로젝트의 규모, 목적, 사용 환경(Node.js, 브라우저, 특정 프레임워크 등)에 따라 매우 다양한 옵션을 가질 수 있습니다. 이 절에서는 가장 중요하고 자주 사용되는 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를 선호합니다.

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를 직접 실행하고 사용하는 방법에 대해 알아보겠습니다.

DefinitelyTyped와 @types

Previous Page

컴파일러 옵션 상세 설명

Next Page