컴파일러 옵션 상세 설명

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+)
  • 권장: true

noUncheckedIndexedAccess와 exactOptionalPropertyTypes는 strict에 포함되지 않는 별도 옵션입니다. 배열·사전의 미확인 접근과 선택 속성의 부재 의미를 강화할 때 각각 설정합니다. 아래 기본값 중 일부는 strict, module 같은 다른 옵션의 영향을 받으므로 실제 설정 조합을 확인해야 합니다.

• 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

  • 설명: 동일한 파일에 대한 참조가 대소문자를 포함하여 일관되지 않을 경우 오류를 발생시킵니다. 이는 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 문에서 모듈의 실제 파일을 찾아내는 전략을 지정합니다.
  • 값: "node16", "nodenext", "bundler" 등. "node"는 과거 Node 해석 방식의 별칭이며 "classic"도 레거시 방식입니다.
  • 선택: 현대 Node.js에서는 module과 함께 node16/nodenext 계열을 맞추고, 번들러에서는 그 도구와 TypeScript 버전이 지원하는 bundler 설정을 사용합니다.

• baseUrl: string (7장 4절 참조)

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

• paths: object (7장 4절 참조)

  • 설명: 모듈 해석 기준에 따라 모듈 가져오기 경로에 대한 별칭(alias) 매핑을 정의합니다. 복잡한 상대 경로를 줄이고 모듈 구조를 추상화하는 데 매우 유용합니다.
  • 예시: "paths": { "@components/*": ["src/components/*"] }
  • 주의: paths는 출력된 import 문자열을 바꾸지 않습니다. 실제 로더나 번들러도 같은 별칭을 해석해야 합니다.

• 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".

target과 lib는 런타임 API를 설치하거나 polyfill을 제공하지 않습니다. 실제 실행 환경의 지원 여부는 별도로 확인합니다.

기타 유용한 옵션

• isolatedModules: boolean (false가 기본값)

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

• allowJs: boolean (false가 기본값)

  • 설명: true로 설정하면, TypeScript 프로젝트에 JavaScript 파일(.js, .jsx)을 프로그램에 포함하고 출력 대상으로 삼을 수 있습니다. JavaScript의 오류 보고는 checkJs 또는 파일의 // @ts-check로 별도 활성화합니다.
  • 권장: 기존 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 개발의 효율성과 안정성을 좌우합니다.

옵션을 바꿀 때는 단일 플래그의 의미보다 타입 검사, 출력, 런타임, 도구 체인이 함께 만들어내는 효과를 한 번에 검토해야 합니다.

옵션의 효과를 입력·검사·해석·출력·도구 층으로 나누어 보면 실패 지점을 좁힐 수 있습니다.