안동민 개발노트 아이콘

안동민 개발노트

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 설정

이전 페이지

프로젝트 레퍼런스

다음 페이지

목차

프로젝트 설정 관련 옵션타입 검사 관련 옵션모듈 관련 옵션JavaScript 런타임 환경 관련 옵션기타 유용한 옵션