TypeScript 대규모 프로젝트, tsc로 똑똑하게 빌드하는 A to Z 🚀

수많은 .ts 파일들이 유기적으로 연결된 TypeScript 프로젝트, 매번 어떻게 컴파일하고 계신가요? 혹시 아직도 개별 파일을 지정하거나 비효율적인 방법으로 시간을 낭비하고 계신다면, 이 글이 여러분의 워크플로우를 혁신적으로 바꿔줄 것입니다. tsconfig.json 파일과 tsc 명령어의 진정한 시너지를 경험해 보세요! ✨

 

---

1. 왜 효율적인 컴파일이 중요할까요? ⏰

개발자에게 시간은 금입니다. 특히 대규모 프로젝트에서는 다음과 같은 이유로 효율적인 컴파일 전략이 필수적입니다.

• 빠른 피드백: 코드 수정 후 결과물을 빠르게 확인해야 개발 흐름이 끊기지 않습니다.
• 리소스 절약: 매번 전체 파일을 다시 읽고 컴파일하는 것은 CPU와 메모리 낭비입니다.
• 일관된 환경: 팀원 모두가 동일한 설정으로 빌드해야 예측 가능한 결과물을 얻을 수 있습니다.

---

2. tsc 명령어, 프로젝트 전체를 바라보다 🔭

tsc (TypeScript Compiler) 명령어는 단순히 .ts 파일을 .js 파일로 변환하는 것을 넘어, 프로젝트 전체를 하나의 단위로 보고 컴파일할 수 있는 강력한 기능을 제공합니다. 이 기능의 핵심은 바로 tsconfig.json 파일에 있습니다.

tsconfig.json 파일의 역할 🔑

• 프로젝트의 루트 디렉토리에 위치하며, TypeScript 컴파일러가 프로젝트를 컴파일하는 방식에 대한 모든 설정을 담고 있습니다.
• 파일 인자 없이 tsc 명령어를 실행하면, 컴파일러는 현재 디렉토리에서 tsconfig.json 파일을 찾아 정의된 설정에 따라 프로젝트 전체를 컴파일합니다.

가장 효율적인 컴파일 명령어 🥇

# 프로젝트 루트 디렉토리에서
tsc

 

네, 맞습니다. 파일 이름을 일일이 지정할 필요 없이, tsconfig.json 파일만 있으면 tsc 명령어 하나로 프로젝트 전체를 효율적으로 컴파일할 수 있습니다. 이것이 가장 기본적인 핵심입니다.

---

3. tsconfig.json 완벽 가이드: 필수 설정 파헤치기 ⚙️

tsconfig.json 파일을 통해 프로젝트 전체 컴파일을 효율적으로 만드는 핵심 옵션들을 자세히 살펴보겠습니다.

3.1. compilerOptions - 컴파일러 동작의 핵심 설정 🛠️

이 객체는 TypeScript 컴파일러가 .ts 파일을 .js 파일로 변환할 때 어떻게 동작할지를 정의합니다.

• target: "ES2020" (또는 "ES6", "ESNext")
  • 생성될 JavaScript 코드의 ECMAScript 대상 버전을 지정합니다. 최신 버전을 선택할수록 .ts 코드가 거의 그대로 .js로 변환되어 실행 성능이 좋습니다.
• module: "commonjs" (또는 "ESNext", "Node16")
  • 생성될 JavaScript 코드의 모듈 시스템을 지정합니다. Node.js 환경에서는 보통 commonjs를, 브라우저 환경에서 번들러와 함께 사용할 때는 ESNext를 많이 사용합니다.
• outDir: "./dist" (예시)
  • 컴파일된 JavaScript 파일(.js 및 .d.ts)들이 저장될 출력 디렉토리 경로를 지정합니다. 모든 결과물이 한곳에 모여 관리하기 편리합니다.
• rootDir: "./src" (예시)
  • TypeScript 소스 파일의 루트 디렉토리를 지정합니다. 이 설정이 있으면 outDir로 출력할 때 rootDir 경로 구조가 유지됩니다.
• strict: true
  • TypeScript의 모든 엄격한 타입 검사 옵션(예: noImplicitAny, strictNullChecks)을 활성화합니다. 개발 초기에는 번거로울 수 있지만, 장기적으로 안정적이고 버그 없는 코드를 작성하는 데 필수적입니다. 강력 권장! ✨
• esModuleInterop: true
  • CommonJS 모듈과 ES 모듈 간의 상호 운용성을 개선하여 import 문법을 더 유연하게 사용할 수 있게 합니다.
• forceConsistentCasingInFileNames: true
  • 파일 이름의 대소문자 일관성을 강제합니다. 파일 시스템에 따라 대소문자를 구분하지 않는 운영체제에서 발생할 수 있는 잠재적 버그를 방지합니다.
• skipLibCheck: true
  • 선언 파일(.d.ts 파일)의 타입 검사를 건너뜁니다. node_modules 폴더의 라이브러리 타입 검사를 생략하여 컴파일 속도를 크게 향상시킬 수 있습니다. 특히 대규모 프로젝트에서 효과적입니다. 🚀

3.2. include, exclude, files - 컴파일 대상 명확화 🎯

• include: ["src/**/*"]
  • 컴파일러가 찾아야 할 소스 파일 경로의 글로벌 패턴 목록입니다. src 폴더 아래의 모든 TypeScript 파일(**/*.ts)을 포함하라는 의미입니다.
• exclude: ["node_modules", "dist"]
  • include에 의해 포함되더라도 컴파일에서 제외할 파일/폴더 목록입니다. node_modules나 이미 빌드된 dist 폴더를 제외하여 불필요한 컴파일을 막고 속도를 높입니다.
• files: ["src/index.ts", "src/types/global.d.ts"]
  • include나 exclude 패턴 대신, 특정 파일 목록만 명시적으로 컴파일하고 싶을 때 사용합니다. (일반적으로는 include를 더 많이 사용합니다.)

// tsconfig.json 예시
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true
  },
  "include": [
    "src/**/*.ts" // src 폴더 내의 모든 .ts 파일 포함
  ],
  "exclude": [
    "node_modules", // node_modules는 제외
    "**/*.spec.ts" // 테스트 파일도 제외 (필요에 따라)
  ]
}

---

4. 생산성을 한층 더 끌어올리는 tsc 꿀팁 🍯

tsc와 tsconfig.json의 기본적인 활용 외에, 개발 경험(DX)을 극대화할 수 있는 추가적인 방법들입니다.

4.1. tsc --init으로 기본 tsconfig.json 생성하기 🚀

새로운 TypeScript 프로젝트를 시작할 때 tsconfig.json을 직접 작성할 필요 없이, 프로젝트 루트에서 다음 명령어를 실행하면 됩니다.

tsc --init

이 명령어는 주석 처리된 다양한 옵션이 포함된 기본 tsconfig.json 파일을 생성해 주므로, 필요에 맞게 수정하여 사용할 수 있습니다.

4.2. incremental 빌드 (증분 컴파일) 활용하기 ⚡

tsconfig.json의 compilerOptions에 "incremental": true를 추가하면, TypeScript 컴파일러는 이전 빌드 정보를 활용하여 변경된 파일만 다시 컴파일합니다. 대규모 프로젝트에서 재빌드 시간을 획기적으로 단축시켜 줍니다.

4.3. watch 모드로 실시간 컴파일하기 🔍

개발 중에는 코드를 수정할 때마다 자동으로 컴파일되도록 watch 모드를 사용하는 것이 좋습니다.

tsc --watch
# 또는 짧게
tsc -w

이 명령어를 실행하면 tsconfig.json 설정에 따라 프로젝트 파일을 지속적으로 감시하고, 변경 사항이 감지될 때마다 필요한 부분만 자동으로 재컴파일해줍니다. 실시간으로 에러를 확인하고 빠르게 결과물을 볼 수 있어 개발 효율이 매우 높아집니다. 🚀

---

5. 요약: TypeScript 프로젝트 컴파일 워크플로우 📝

1. 프로젝트 초기화: tsc --init으로 tsconfig.json 파일을 생성합니다.
2. 설정 최적화: target, module, outDir, rootDir, strict, skipLibCheck, include, exclude 등의 옵션을 프로젝트에 맞게 설정합니다. 특히 incremental: true를 추가하여 증분 빌드를 활성화하는 것을 잊지 마세요.
3. 한 번에 빌드: 배포 전이나 전체 프로젝트 빌드가 필요할 때는 프로젝트 루트에서 tsc만 입력합니다.
4. 개발 중 실시간 빌드: 코드 수정 중에는 tsc --watch를 사용하여 자동 컴파일 및 피드백을 받습니다.

---

🏁 마무리하며

TypeScript 프로젝트에서 .ts 파일이 아무리 많아져도 tsc와 tsconfig.json의 강력한 조합만 있다면 걱정할 필요가 없습니다. 이 가이드를 통해 여러분의 TypeScript 개발 워크플로우가 더욱 효율적이고 즐거워지기를 바랍니다! 💡 Happy Coding!