카테고리 없음

TypeScript 30강: 타입스크립트 프로젝트 구조와 빌드 설정 가이드

mystory55776 2025. 5. 30. 23:48

TypeScript 프로젝트를 어떻게 구조화할까?

타입스크립트(TypeScript)로 안정적인 애플리케이션을 개발하려면, 명확한 프로젝트 구조와 체계적인 빌드 설정이 필수입니다. 특히 규모가 커질수록 유지보수에 영향을 주기 때문에, 디렉토리 구성과 tsconfig.json 설정을 초기부터 잘 설계해야 합니다.

기본 디렉토리 구조 예시

아래는 일반적인 타입스크립트 프로젝트의 구조입니다.

my-typescript-app/
├── src/
│   ├── index.ts
│   └── modules/
│       └── user.ts
├── dist/
├── tsconfig.json
├── package.json
  • src/: 소스 코드가 위치하는 디렉토리
  • dist/: 컴파일된 JavaScript 파일 출력 디렉토리
  • tsconfig.json: TypeScript 설정 파일

src와 dist 디렉토리를 명확히 구분하면, 빌드 결과물과 원본 소스를 체계적으로 관리할 수 있습니다.

tsconfig.json 기본 설정 구성

tsconfig.json은 TypeScript 컴파일러가 프로젝트를 어떻게 빌드할지 설정하는 핵심 파일입니다. 다음은 실무에서 자주 사용하는 설정 예입니다.

{
  "compilerOptions": {
    "target": "ES6",
    "module": "ES6",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "moduleResolution": "node",
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

주요 compilerOptions 설명

  • target: 출력 JavaScript 버전 설정 (예: ES5, ES6)
  • module: 모듈 시스템 설정 (예: CommonJS, ES6)
  • rootDir: 타입스크립트 원본 코드 디렉토리
  • outDir: 컴파일된 코드의 출력 디렉토리
  • strict: 엄격한 타입 검사 활성화
  • esModuleInterop: CommonJS와의 호환성 확보
  • moduleResolution: 모듈 해석 방식 지정 (node 권장)

특히 strict 옵션은 타입 안정성을 강화하는 데 중요하며, 실무에서 필수로 사용됩니다.

빌드 스크립트 설정하기

package.json 파일에 빌드 스크립트를 추가하면 명령어 하나로 프로젝트를 컴파일할 수 있습니다.

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

이제 npm run build 명령으로 TypeScript를 컴파일하고, npm start로 실행할 수 있습니다.

tsc CLI 명령어 정리

TypeScript CLI(tsc)를 사용하면 다양한 빌드 명령을 직접 실행할 수 있습니다.

  • tsc: tsconfig.json 설정을 기반으로 전체 프로젝트 빌드
  • tsc -w: 변경 사항 감지하며 실시간 빌드
  • tsc src/index.ts: 단일 파일 컴파일

프로젝트 환경에 따라 필요한 설정 예시

환경별로 설정을 커스터마이즈하면 더욱 유용합니다.

  • Node.js 프로젝트: module: "CommonJS", target: "ES2020"
  • 브라우저 환경: module: "ES6", lib: ["DOM", "ES6"]
  • React 프로젝트: JSX 설정 추가, "jsx": "react-jsx"

타입 선언과 외부 라이브러리 설정

외부 JavaScript 라이브러리를 사용할 경우, 해당 라이브러리의 타입 정의 파일이 필요합니다. 예:

npm install lodash
npm install --save-dev @types/lodash

이렇게 하면 타입 오류 없이 안전하게 라이브러리를 사용할 수 있습니다.

정리: 효율적인 TypeScript 프로젝트 설정 가이드

타입스크립트 프로젝트는 초기 구조 설정과 빌드 환경 구성이 핵심입니다. 아래 내용을 기억하세요.

  • src/dist 디렉토리를 구분하여 코드와 빌드 결과물을 분리
  • tsconfig.json을 통해 타입 검사 및 컴파일 옵션 세분화
  • npm 스크립트로 빌드 및 실행을 자동화
  • 외부 타입 정의 설치로 안정적인 외부 라이브러리 사용

이러한 구성을 기반으로 하면, 유지보수성과 확장성이 뛰어난 타입스크립트 프로젝트를 만들 수 있습니다.