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

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 스크립트로 빌드 및 실행을 자동화
외부 타입 정의 설치로 안정적인 외부 라이브러리 사용

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

mystory55776 님의 블로그