Project Reference: Monorepo TS

"Project reference 가 monorepo 를 분할해서 compiler 가 안 바뀐 거 재체크 피하게."

문제

여러 TypeScript 패키지 (예: `packages/api`, `packages/web`, `packages/shared`) 가진 monorepo 에서, naive `tsc` 가 매번 모든 거 재체크. 큰 monorepo 엔 분 단위 걸림 — 개발 loop 엔 너무 길어.

Project reference

각 패키지가 자기 `tsconfig.json` 받음. Root `tsconfig.json` 이 모든 패키지를 `references` 로 나열. 패키지가 의존하는 곳 같은 필드 통해 서로도 reference.

tsc -b (build mode) 가 reference 읽고, dependency 그래프 계산, topological 순서로 컴파일. 결과가 `.tsbuildinfo` 파일에 cache. 후속 실행에 입력 바뀐 패키지만 재컴파일 — 그리고 직접 dependent 만 재체크 필요.

각 패키지의 tsconfig 가 `composite: true` 필요

Project-reference 패키지가 tsconfig 에 "composite": true 설정해야. 이게 incremental build 활성화, 명시 `outDir` 요구, declaration emission 강제 (dependent 가 타입 읽을 수 있게). Flag 가 opt-in.

Project reference 가 monorepo 에서 TS scale 하는 canonical 방법. 없으면 모든 체크가 모든 거 rebuild; 있으면 영향받은 패키지만.

Code

Project reference setup — root 과 패키지·json

// Root tsconfig.json — orchestrator.
{
  "files": [],
  "references": [
    { "path": "./packages/shared" },
    { "path": "./packages/api" },
    { "path": "./packages/web" }
  ]
}

// packages/shared/tsconfig.json — composite 프로젝트.
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}

// packages/api/tsconfig.json — shared reference.
{
  "compilerOptions": {
    "composite": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "references": [{ "path": "../shared" }]
}

Exercise

작은 2-패키지 monorepo setup: pkg-a 가 함수 export, pkg-b 가 import. Project reference 구성. tsc -b 돌려. pkg-a 변경, 다시 돌려 — 전 세계 아니라 pkg-a 와 pkg-b 만 rebuild 확인.

Hint

첫 build 후 .tsbuildinfo 파일이 각 패키지에 나타남. 두 번째 build 가 그거 읽고 pkg-a 의 입력만 바뀐 거 보고 pkg-a + 그것의 dependent 만 재컴파일.

Project Reference: Monorepo TS

문제