TypeScript를 실무에 적용하려 할 때 가장 먼저 마주하게 되는 설정 파일이 바로 tsconfig.json입니다. 이 파일은 프로젝트의 타입스크립트 환경을 설정하고, 컴파일러가 어떻게 작동할지 세부적으로 제어할 수 있도록 돕습니다. 하지만 초보 개발자나 심지어 일부 실무 개발자에게도 이 설정 파일은 여전히 어렵고 낯선 존재입니다.
본 글에서는 TypeScript의 핵심 설정 파일인 tsconfig.json을 중심으로 주요 옵션들을 완전 분석하고, 실무에 적용 가능한 꿀팁들을 제시하겠습니다.
tsconfig.json의 기본 구조 이해하기
tsconfig.json은 TypeScript 컴파일러에게 프로젝트 설정을 전달하는 JSON 형식의 구성 파일입니다. 가장 기본적인 구조는 compilerOptions, include, exclude 세 가지로 나눌 수 있습니다. compilerOptions는 컴파일러가 코드를 어떻게 해석하고 출력할지 지정하며, include는 어떤 파일을 컴파일할지, exclude는 제외할 파일을 명시합니다.
예를 들어, 다음과 같은 구조를 가질 수 있습니다:
{
"compilerOptions": {
"target": "ES6",
"module": "commonjs",
"strict": true,
"esModuleInterop": true
},
"include": ["src"],
"exclude": ["node_modules"]
}
target은 출력할 JavaScript 버전을, module은 사용 모듈 시스템을, strict는 타입 검사 수준을 제어합니다. 이 외에도 수십 가지의 세부 옵션이 존재합니다. 중요한 점은 이 설정이 프로젝트의 전체 안정성과 빌드 결과에 직접적인 영향을 준다는 것입니다.
기본 구조를 이해했다면, 이제 각 설정들이 어떤 의미를 갖는지 구체적으로 살펴볼 필요가 있습니다. 실무에서는 프로젝트 규모나 팀의 코딩 스타일, 배포 환경에 따라 최적의 설정이 달라지기 때문입니다.
주요 compilerOptions 설정 완전 정복
TypeScript의 가장 강력한 설정 영역은 단연 compilerOptions입니다. 이 옵션들을 적절히 활용하면, 프로젝트의 타입 안정성을 크게 높일 수 있으며, 개발자 경험도 개선할 수 있습니다.
먼저 strict 옵션은 여러 개의 엄격한 검사 플래그(noImplicitAny, strictNullChecks, alwaysStrict 등)를 한꺼번에 활성화해줍니다. 실무에서는 대부분 strict: true 설정이 권장됩니다. 이유는 코드의 안정성을 보장하고, 미리 에러를 예방할 수 있기 때문입니다.
esModuleInterop은 CommonJS 모듈을 ES Module 방식으로 import 할 수 있도록 해주는 옵션으로, 외부 라이브러리를 사용할 때 매우 유용합니다. 이 옵션이 없으면 import express from 'express' 와 같은 구문이 에러를 일으킬 수 있습니다.
baseUrl과 paths는 모듈 경로를 alias 처리해 코드 가독성과 유지보수성을 높이는 데 활용됩니다. 예를 들어 import Button from '../../../components/Button' 대신 import Button from '@/components/Button'처럼 간결한 경로 설정이 가능해집니다.
lib은 프로젝트가 사용할 수 있는 API 라이브러리 집합을 지정합니다. 기본적으로는 ["DOM", "ES6"] 등을 사용하며, 백엔드 프로젝트에서는 ["ES2021"]과 같은 설정이 자주 사용됩니다. 이 외에도 skipLibCheck, noEmit, declaration 등의 옵션이 실무에서 자주 활용됩니다.
모든 옵션을 한 번에 이해하기는 어렵지만, 프로젝트 목적에 따라 우선순위를 두고 설정을 구성해 나가는 것이 중요합니다. 특히 대규모 협업 프로젝트에서는 공통된 tsconfig 규칙을 정하고, ESLint와 함께 활용하는 방식이 안정적인 개발에 많은 도움이 됩니다.
실무 환경에서의 설정 팁과 최적화 전략
실제 업무에서 TypeScript 설정을 잘 구성하려면 팀 규모, 프로젝트 성격, 프레임워크 종류 등을 고려해야 합니다. 예를 들어 React 기반의 프런트엔드 프로젝트라면 jsx, allowSyntheticDefaultImports, moduleResolution 같은 옵션을 조정해야 하며, Node.js 기반의 백엔드 프로젝트라면 outDir, rootDir 설정을 꼼꼼히 관리해야 합니다.
대규모 프로젝트에서는 설정 파일을 계층적으로 나누는 방법이 유용합니다. 예를 들어 tsconfig.base.json을 생성해 공통 설정을 관리하고, 각 모듈 또는 앱에서 이를 상속하는 방식입니다. 다음과 같은 구조가 일반적입니다:
// tsconfig.base.json
{
"compilerOptions": {
"strict": true,
"esModuleInterop": true,
"baseUrl": "./src"
}
}
// tsconfig.json
{
"extends": "./tsconfig.base.json",
"include": ["src/moduleA"]
}
이러한 설정 분리는 유지보수를 단순화하고, 설정 충돌을 방지하는 데 효과적입니다. 또한 GitHub의 tsconfig/bases 프로젝트를 참고하면 다양한 환경별 템플릿을 활용할 수 있어 시작이 훨씬 쉬워집니다.
마지막으로는 설정 변경 후 tsc --noEmit 명령어를 활용해 전체 프로젝트가 잘 작동하는지 타입 검사만 수행해보는 것도 좋은 습관입니다. 이는 CI/CD 환경에서도 자주 활용되는 방식으로, 코드의 타입 안정성을 자동으로 검증해 주는 역할을 합니다.
결국 TypeScript 설정을 잘 활용하면 개발자 생산성을 높이고, 오류를 사전에 예방하며, 협업을 더욱 원활하게 만들 수 있습니다.
TypeScript를 처음 접할 때 tsconfig.json은 다소 어렵게 느껴질 수 있지만, 설정 하나하나의 의미를 이해하고 적용해 나간다면 훨씬 견고하고 안정적인 프로젝트를 만들 수 있습니다. 지금 사용하는 설정을 다시 점검해보고, 필요한 부분을 개선해 보는 것이 성장의 지름길입니다. 현업에서도 당장 적용 가능한 팁들을 통해 실력을 빠르게 높여보세요!