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

컴파일러 옵션 상세 설명

9.1절에서 tsconfig.json 파일의 중요성과 기본적인 구조를 살펴보았습니다. 이제 compilerOptions 내부에 있는 주요 옵션들을 좀 더 깊이 있게 파고들어 보겠습니다. 각 옵션이 어떤 역할을 하고, 프로젝트에 어떤 영향을 미 미치는지 이해하는 것은 타입스크립트 개발을 최적화하는 데 필수적입니다.

프로젝트 설정 관련 옵션

이 옵션들은 프로젝트의 전반적인 구조와 컴파일러의 파일 탐색 방식에 영향을 줍니다.

  • rootDir: string

    • 설명: TypeScript 소스 파일이 위치한 프로젝트의 루트 디렉토리를 지정합니다. outDir로 출력될 파일 경로는 이 rootDir를 기준으로 상대적으로 유지됩니다. 예를 들어, rootDir: "./src"이고 src/components/button.ts 파일이 outDir: "./dist"로 컴파일되면 dist/components/button.js로 생성됩니다.
    • 권장: 일반적으로 소스 코드가 시작되는 src 폴더로 설정합니다.

  • outDir: string

    • 설명: 컴파일된 JavaScript 파일(.js), 타입 정의 파일(.d.ts), 소스 맵 파일(.map) 등 모든 출력 파일이 저장될 디렉토리를 지정합니다.
    • 권장: dist 또는 build와 같이 프로젝트 빌드 결과물을 위한 전용 폴더로 설정합니다.

  • declaration: boolean (false가 기본값)

    • 설명: true로 설정하면, TypeScript 소스 파일(.ts)과 함께 타입 정의 파일(.d.ts)을 자동으로 생성합니다. 이는 특히 라이브러리를 개발하고 배포할 때 필수적입니다. 소비하는 프로젝트가 라이브러리의 타입을 이해하는 데 이 .d.ts 파일이 사용됩니다.
    • 권장: 라이브러리 프로젝트에서 true, 애플리케이션 프로젝트에서는 false 또는 필요에 따라 true.

  • sourceMap: boolean (false가 기본값)

    • 설명: true로 설정하면, 컴파일된 JavaScript 파일과 원본 TypeScript 소스 파일 간의 매핑 정보를 담은 소스 맵 파일(.map)을 생성합니다. 이 파일은 브라우저 개발자 도구나 Node.js 디버거에서 컴파일된 JS 코드가 아닌 원래 TS 코드에서 직접 디버깅할 수 있게 해줍니다.
    • 권장: 개발 환경에서는 true, 프로덕션 빌드에서는 필요에 따라 true 또는 false (소스 맵이 노출될 수 있으므로).

  • outFile: string (ES 모듈이 아닌 경우에만 사용)

    • 설명: 모든 컴파일된 JavaScript 코드를 단일 파일로 합칠 때 사용합니다. 이 옵션은 module 옵션이 "none", "system", "amd" 중 하나일 때만 유효합니다. CommonJS나 ES 모듈에서는 사용할 수 없습니다.
    • 권장: 거의 사용되지 않습니다. 현대 웹 개발에서는 웹팩 같은 번들러가 이 역할을 대신합니다.

타입 검사 관련 옵션

이 옵션들은 TypeScript 컴파일러가 코드를 얼마나 엄격하게 타입 검사할지를 제어합니다. 엄격한 검사는 초기 개발 단계에서는 번거롭게 느껴질 수 있지만, 장기적으로는 버그를 줄이고 코드의 안정성을 높이는 데 기여합니다.

  • strict: boolean (false가 기본값)

    • 설명: true로 설정하면, 아래의 모든 엄격한 타입 검사 옵션을 한 번에 활성화합니다. TypeScript를 사용하는 주된 이유이므로 true로 설정하는 것이 강력히 권장됩니다.
      • noImplicitAny
      • strictNullChecks
      • strictFunctionTypes
      • strictBindCallApply
      • strictPropertyInitialization
      • noImplicitThis
      • useUnknownInCatchVariables (TS 4.4+)
      • noUncheckedIndexedAccess (TS 4.1+)
    • 권장: true

  • noImplicitAny: boolean (false가 기본값)

    • 설명: 타입스크립트가 타입을 any로 암시적으로 추론할 수 있는 경우(예: 타입이 명시되지 않은 변수, 함수의 매개변수)에 오류를 발생시킵니다.
    • 권장: strict: true에 포함되므로, 일반적으로 직접 설정하지 않습니다.

  • strictNullChecks: boolean (false가 기본값)

    • 설명: null과 undefined 값을 일반적인 다른 타입에 할당할 수 없도록 강제합니다. 즉, string | null과 같이 명시적으로 null을 허용해야 합니다. null 또는 undefined 관련 런타임 오류를 방지하는 데 매우 효과적입니다.
    • 권장: strict: true에 포함되므로, 일반적으로 직접 설정하지 않습니다.

  • noUnusedLocals: boolean (false가 기본값)

    • 설명: 선언되었지만 사용되지 않는 지역 변수에 대해 오류를 발생시킵니다. 죽은 코드(dead code)를 제거하고 코드 베이스를 깔끔하게 유지하는 데 도움이 됩니다.
    • 권장: true

  • noUnusedParameters: boolean (false가 기본값)

    • 설명: 선언되었지만 사용되지 않는 함수 매개변수에 대해 오류를 발생시킵니다.
    • 권장: true (특히 콜백 함수의 경우, 사용하지 않는 매개변수는 _로 명시하여 의도를 밝힐 수 있습니다.)

  • noImplicitReturns: boolean (false가 기본값)

    • 설명: 함수에서 일부 코드 경로가 값을 반환하지 않을 때 (그러나 다른 경로는 반환할 때) 오류를 발생시킵니다. 모든 코드 경로가 동일한 반환 타입을 가지도록 강제합니다.
    • 권장: true

  • noFallthroughCasesInSwitch: boolean (false가 기본값)

    • 설명: switch 문에서 case 블록이 다음 case 블록으로 fallthrough 되는 경우(즉, break나 return이 없는 경우) 오류를 발생시킵니다.
    • 권장: true

  • forceConsistentCasingInFileNames: boolean (false가 기본값)

    • 설명: 동일한 파일에 대한 참조가 대소문자를 포함하여 일관되지 않을 경우 오류를 발생시킵니다. 이는 Windows/macOS(대소문자 구분 안 함)와 Linux(대소문자 구분) 간의 빌드 문제나 모듈 해결 문제를 방지합니다.
    • 권장: true

모듈 관련 옵션

이 옵션들은 TypeScript가 모듈을 어떻게 해석하고 JavaScript로 변환할지 제어합니다.

  • module: string (9.1절 참조)

    • 설명: 생성될 JavaScript 코드의 모듈 형식을 지정합니다.
    • 권장: Node.js 백엔드에서는 "commonjs", 프론트엔드 + 번들러 환경에서는 "esnext" 또는 "es2020" 이상. Node.js 16 이상 ES 모듈 프로젝트에서는 "node16" 또는 "nodenext".

  • moduleResolution: string (7.4절 참조)

    • 설명: TypeScript가 import 문에서 모듈의 실제 파일을 찾아내는 전략을 지정합니다.
    • 값: "node", "bundler", "classic"
    • 권장: Node.js 환경에서는 "node", 최신 웹 번들러 환경에서는 "bundler" (TS 5.0 이상).

  • baseUrl: string (7.4절 참조)

    • 설명: 비-상대 모듈(import 'module-name')의 기준이 되는 디렉토리를 지정합니다. 이 옵션이 설정되면, TypeScript는 node_modules를 검색하기 전에 baseUrl을 기준으로 모듈을 찾으려고 시도합니다.
    • 권장: 프로젝트의 소스 루트 (., ./src 등)로 설정하여 절대 경로 임포트를 가능하게 합니다.

  • paths: object (7.4절 참조)

    • 설명: baseUrl과 함께 사용하여 모듈 가져오기 경로에 대한 별칭(alias) 매핑을 정의합니다. 복잡한 상대 경로를 줄이고 모듈 구조를 추상화하는 데 매우 유용합니다.
    • 예시: "paths": { "@components/*": ["src/components/*"] }
    • 권장: 프로젝트 규모가 커지면 적극적으로 활용합니다.

  • esModuleInterop: boolean (false가 기본값) (7.2절 참조)

    • 설명: CommonJS 모듈의 export와 ES 모듈의 import 구문 간의 상호 운용성을 향상시킵니다. 이 옵션을 true로 설정하면 CommonJS 모듈의 기본 내보내기를 import MyModule from 'my-module'과 같이 자연스럽게 가져올 수 있도록 컴파일러가 헬퍼 코드를 추가합니다.
    • 권장: true (대부분의 현대 프로젝트에서 필요).

  • allowSyntheticDefaultImports: boolean (false가 기본값)

    • 설명: 모듈이 기본 내보내기(export default)를 하지 않더라도, 마치 기본 내보내기가 있는 것처럼 import X from 'module' 구문을 사용할 수 있도록 허용합니다. esModuleInterop: true를 설정하면 이 옵션도 암시적으로 true가 됩니다.

JavaScript 런타임 환경 관련 옵션

  • target: string (9.1절 참조)

    • 설명: 생성될 JavaScript 코드의 ECMAScript 버전을 지정합니다. 이는 어떤 JS 문법을 그대로 유지하고 어떤 문법을 하위 버전으로 트랜스파일할지 결정합니다.
    • 권장: 지원해야 하는 가장 낮은 런타임 환경에 맞춥니다.

  • lib: string[] (9.1절 참조)

    • 설명: 컴파일 시 코드에 포함할 표준 내장 API 정의 파일 목록을 지정합니다. 예를 들어, dom을 추가하면 document, window 등의 전역 객체와 관련된 타입이 제공됩니다.
    • 권장: target과 함께 프로젝트가 실행될 환경에 맞게 설정합니다 (예: 브라우저 환경은 dom 포함).

  • jsx: string (9.1절 참조)

    • 설명: JSX 구문을 어떻게 처리할지 지정합니다.
    • 값: "preserve", "react", "react-jsx", "react-jsxdev", "react-native"
    • 권장: React 17+에서는 "react-jsx", 이전 버전에서는 "react".

기타 유용한 옵션

  • isolatedModules: boolean (false가 기본값)

    • 설명: true로 설정하면, 각 파일이 독립적인 모듈로 안전하게 트랜스파일될 수 있는지 확인합니다. transpileModule API와 같은 단일 파일 트랜스파일러(예: Babel)를 사용할 때 발생하는 문제를 방지합니다. 일부 TS 기능(예: const enum이 isolatedModules에서 안전하게 제거되지 않을 수 있음)에 제약이 생길 수 있습니다.
    • 권장: Vite, esbuild 등 모듈별로 트랜스파일하는 번들러를 사용할 때 true.

  • allowJs: boolean (false가 기본값)

    • 설명: true로 설정하면, TypeScript 프로젝트에 JavaScript 파일(.js, .jsx)을 포함하여 타입 검사하고 컴파일할 수 있습니다.
    • 권장: 기존 JavaScript 프로젝트를 TypeScript로 점진적으로 전환할 때 유용.

  • checkJs: boolean (false가 기본값)

    • 설명: allowJs가 true일 때, JavaScript 파일에 대해서도 TypeScript의 타입 검사를 수행합니다. JSDoc 주석을 기반으로 타입을 추론하고 오류를 보고합니다.
    • 권장: JavaScript 파일에 대한 타입 검사를 강화하고 싶을 때 유용.

  • noEmit: boolean (false가 기본값)

    • 설명: true로 설정하면, 컴파일러가 JavaScript 출력 파일을 생성하지 않고 오직 타입 검사만 수행합니다. 번들러(Webpack, Vite)가 트랜스파일을 담당하고 TypeScript는 타입 검사만 수행할 때 유용합니다.
    • 권장: 번들러를 사용하여 최종 빌드를 수행하는 프로젝트에서 true.

  • incremental: boolean (false가 기본값)

    • 설명: true로 설정하면, 컴파일러는 이전 컴파일의 정보를 저장하여 이후 컴파일 시 증분 컴파일을 수행합니다. 이는 컴파일 시간을 크게 단축시킵니다.
    • 권장: 개발 환경에서 컴파일 시간을 줄이기 위해 true.

tsconfig.json의 compilerOptions는 매우 많고 다양하지만, 위에 설명된 옵션들은 대부분의 타입스크립트 프로젝트에서 공통적으로 마주하고 설정해야 하는 핵심적인 부분입니다. 프로젝트의 특성과 요구사항에 맞게 이 옵션들을 정확히 이해하고 설정하는 것이 TypeScript 개발의 효율성과 안정성을 좌우합니다.

tsconfig.json 설정

Previous Page

프로젝트 레퍼런스

Next Page