프로젝트 참조: 큰 저장소의 타입 경계 세우기

"프로젝트 참조는 바뀌지 않은 패키지를 매번 다시 검사하지 않도록 모노레포를 나눠."

문제

api, web, shared 같은 여러 TypeScript 패키지가 있는 모노레포를 하나의 프로젝트로 검사하면 매번 전체를 다시 읽어 대규모 저장소에서는 몇 분이 걸릴 수 있어.

프로젝트 참조

각 패키지는 자체 tsconfig를 갖고 루트 tsconfig의 references가 패키지들을 나열해. 패키지 사이 의존도 같은 필드로 연결해.

tsc -b는 참조 그래프를 위상 순서로 빌드하고 결과를 .tsbuildinfo에 저장해. 다음 실행에서는 입력이 바뀐 패키지와 직접 의존하는 패키지만 다시 검사하므로 전체 재검사가 분 단위라면 결과를 초 단위로 줄일 수 있어.

각 패키지는 composite가 필요해

참조되는 패키지는 composite: true를 켜고 명시적인 outDir과 선언 출력을 제공해야 해. 이 설정이 증분 패키지 경계에 참여한다는 명시적 선택이야.

프로젝트 참조는 TypeScript 모노레포를 확장하는 표준 도구야. 참조가 없으면 전체를, 참조가 있으면 영향받은 패키지만 다시 검사해.

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

함수를 내보내는 pkg-a와 그 함수를 가져오는 pkg-b로 작은 두 패키지 모노레포를 만들고 프로젝트 참조를 설정해. tsc -b로 빌드한 뒤 pkg-a를 수정해 다시 실행하고, pkg-a와 그 의존 패키지인 pkg-b만 다시 빌드되는지 확인해.

Hint

첫 빌드 뒤 각 패키지의 .tsbuildinfo를 확인해. pkg-a를 바꾼 다음 pkg-a와 직접 의존하는 pkg-b만 다시 검사되는지 봐.

문제