icon안동민 개발노트

프로젝트 레퍼런스


 프로젝트 레퍼런스는 TypeScript 프로젝트를 더 작고 관리하기 쉬운 부분으로 나누는 방법을 제공합니다.

 이는 대규모 코드베이스를 효율적으로 구성하고 빌드 성능을 최적화하는 데 중요한 역할을 합니다.

개념과 필요성

 프로젝트 레퍼런스는 다음과 같은 이점을 제공합니다.

  • 프로젝트 구조의 논리적 분리
  • 빌드 시간 단축
  • 타입 검사 성능 향상
  • 코드 구성의 유연성 증가

설정 방법

 tsconfig.json에서 프로젝트 레퍼런스를 설정하는 방법

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "references": [
    { "path": "../common" },
    { "path": "../api" }
  ]
}

 여기서 composite 옵션은 프로젝트를 복합 프로젝트로 만들며, references 배열은 의존하는 다른 프로젝트를 지정합니다.

복합 프로젝트 (Composite Projects)

 복합 프로젝트는 다음 특징을 가집니다.

  • composite 플래그가 true로 설정
  • declaration 옵션 필수
  • rootDir 설정 필요

 복합 프로젝트 구조 예시

/project
  /common
    tsconfig.json
    /src
      utils.ts
  /api
    tsconfig.json
    /src
      server.ts
  /client
    tsconfig.json
    /src
      app.ts

 각 하위 프로젝트의 tsconfig.json은 다른 프로젝트를 참조할 수 있습니다.

빌드 최적화

 프로젝트 레퍼런스를 사용한 빌드 최적화

  1. 증분 빌드: 변경된 프로젝트만 다시 빌드
  2. 병렬 빌드: 독립적인 프로젝트 동시 빌드

 명령어 예시

tsc --build src/tsconfig.json

 증분 빌드의 작동 원리

  • 이전 빌드 정보 저장 (.tsbuildinfo 파일)
  • 변경 감지 및 필요한 부분만 재빌드

의존성 관리

 프로젝트 간 의존성 관리

  1. 명시적 참조 사용
  2. 순환 참조 방지

 순환 참조 해결 전략

  • 공통 모듈 추출
  • 의존성 방향 재설계

Solution-Style tsconfig

 TypeScript 4.0에서 도입된 Solution-Style tsconfig

{
  "files": [],
  "references": [
    { "path": "./common" },
    { "path": "./api" },
    { "path": "./client" }
  ]
}

 이 파일은 전체 프로젝트 구조를 정의하며, 단일 명령으로 모든 프로젝트를 빌드할 수 있게 합니다.

일반적인 문제와 해결 방법

 1. 경로 해석 문제

  • 해결 : baseUrlpaths 옵션 올바르게 설정

 2. 빌드 순서 문제

  • 해결 : 의존성 그래프에 따라 올바른 순서로 참조 설정

 3. 타입 정의 파일 누락

  • 해결 : declaration 옵션 확인 및 출력 경로 설정 검토

Best Practices

 1. 모듈성 강화

  • 논리적으로 분리 가능한 단위로 프로젝트 구성

 2. 일관된 구조 유지

  • 각 하위 프로젝트에 유사한 구조 적용

 3. 의존성 그래프 최적화

  • 순환 의존성 제거 및 의존성 계층 단순화

 4. 빌드 스크립트 자동화

  • npm 스크립트 또는 빌드 도구를 사용한 빌드 프로세스 자동화

 5. 버전 관리 전략

  • 각 하위 프로젝트의 버전을 독립적으로 관리

 6. 테스트 전략

  • 각 프로젝트별 단위 테스트 및 통합 테스트 구성

 7. 문서화

  • 프로젝트 구조 및 의존성 관계 명확히 문서화