프로젝트 레퍼런스

대규모 타입스크립트 프로젝트를 운영하다 보면 하나의 거대한 tsconfig.json과 단일 컴파일 흐름만으로는 효율적인 관리가 어려워지는 시점이 옵니다.

특히 모노레포(Monorepo)에서 여러 하위 프로젝트가 서로 의존할 때 이 문제가 더 뚜렷하게 드러납니다.

모든 코드를 한 번에 컴파일하면 시간이 오래 걸리고, 작은 변경도 전체 빌드를 다시 시작하게 만들어 생산성을 떨어뜨릴 수 있습니다.

타입스크립트 3.0부터 도입된 프로젝트 레퍼런스(Project References) 기능은 이러한 문제를 해결하기 위한 방법입니다.

이 기능은 큰 타입스크립트 프로젝트를 각각 tsconfig.json 파일을 가진 여러 개의 작은 하위 프로젝트로 분할하고, 이들이 서로의 의존성을 명시적으로 참조할 수 있도록 합니다.

왜 프로젝트 레퍼런스를 사용해야 하는가?

프로젝트 레퍼런스를 사용하면 다음과 같은 주요 이점을 얻을 수 있습니다.

프로젝트 레퍼런스 설정 방법

그림은 두 소비자가 shared에 의존하는 확장 구조입니다. 아래 코드는 이를 ui → common 한 갈래로 줄인 예입니다. 화살표는 참조 방향이며 실제 빌드는 의존 대상부터 수행합니다.

프로젝트 레퍼런스를 사용하려면, 의존성을 가지는 각 하위 프로젝트의 tsconfig.json 파일에 몇 가지 변경 사항을 적용해야 합니다.

common 프로젝트는 다른 프로젝트가 의존할 타입 정의 파일(.d.ts)을 생성해야 합니다.

{
  "compilerOptions": {
    "target": "es2020",
    "module": "esnext",
    "outDir": "./dist",        // 컴파일된 JS 파일과 .d.ts 파일이 저장될 곳
    "rootDir": "./src",
    "declaration": true,       // 필수: .d.ts 파일 생성 활성화
    "declarationMap": true,    // 선택: .d.ts.map 파일 생성 (원본 TS 파일로 이동 가능)
    "composite": true,         // 필수: 이 프로젝트가 다른 프로젝트에 의해 참조될 것임을 나타냄
    "strict": true
  },
  "include": [
    "src/**/*.ts"
  ]
}

• "declaration": true: 이 프로젝트가 다른 프로젝트에서 사용할 타입 정보를 포함하는 .d.ts 파일을 생성하도록 지시합니다.
• "composite": true: 이 프로젝트가 다른 tsconfig.json에 의해 참조될 수 있는 프로젝트임을 나타내는 플래그입니다. 이 옵션에서는 선언 출력이 필요하며 declaration의 기본값이 true가 됩니다. declarationMap은 별도로 켜야 합니다.

ui 프로젝트는 common 프로젝트가 제공하는 타입에 의존합니다.

references 배열을 사용하여 이 의존성을 명시합니다.

{
  "compilerOptions": {
    "target": "es2020",
    "module": "esnext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "composite": true
  },
  "include": [
    "src/**/*.ts"
  ],
  "references": [
    { "path": "../common" } // common 프로젝트를 참조합니다.
  ]
}

• "references": []: 이 배열 안에 현재 프로젝트가 의존하는 다른 tsconfig.json 파일의 경로를 지정합니다. 경로는 현재 tsconfig.json 파일을 기준으로 합니다.

모노레포의 루트에 있는 tsconfig.json은 일반적으로 직접 코드를 컴파일하기보다는, 하위 프로젝트들의 빌드 순서를 관리하고 증분 빌드를 트리거하는 역할을 합니다.

{
  "files": [], // 이 tsconfig 자체는 컴파일할 파일이 없으므로 비워둡니다.
  "references": [
    { "path": "./packages/common" }, // common 프로젝트를 먼저 빌드해야 합니다.
    { "path": "./packages/ui" }      // ui 프로젝트는 common에 의존하므로 그 다음에 빌드됩니다.
  ]
}

• "files": []: 이 루트 tsconfig.json은 직접 소스 파일을 컴파일하지 않고, 단지 하위 프로젝트들을 참조만 하므로 files나 include를 비워두는 것이 일반적입니다. 참조와 import는 서로 다른 선언입니다. references는 프로젝트의 타입·빌드 의존성을 지정하지만, 소비자의 코드에 import를 자동으로 추가하지는 않습니다. import를 적었다고 참조 대상이 자동 빌드되는 것도 아닙니다. tsc -p packages/ui는 ui를 검사하는 명령이고, 필요한 생산자까지 준비하는 명령은 tsc -b입니다. 루트 배열에서 ui를 먼저 적어도 ui의 참조 그래프가 common을 가리키면 common부터 빌드합니다.

• "references": []: 여기에 모든 하위 프로젝트를 나열합니다. tsc --build 명령을 사용하면 TypeScript는 이 references 배열을 기반으로 올바른 빌드 순서를 자동으로 추론합니다.

프로젝트 레퍼런스 사용하기

루트에서 참조하는 common과 ui는 모두 composite: true로 구성했습니다. 설정을 완성한 후 다음 명령을 사용합니다.

# 루트 디렉토리에서 실행
tsc --build # 또는 tsc -b

tsc --build 명령은 다음과 같은 작업을 수행합니다.

common/types 같은 지정자를 타입 검사에서 해석하는 한 방법이 paths입니다. 실제 workspace 패키지의 exports/타입 선언을 구성하는 방법도 있으며, 아래 별칭만으로 Node.js 런타임의 패키지가 만들어지지는 않습니다.

my-monorepo/packages/ui/tsconfig.json 수정

{
  "compilerOptions": {
    "target": "es2020",
    "module": "esnext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "composite": true,
    "baseUrl": ".", // paths의 기준 디렉토리로 사용; baseUrl 자체가 필수는 아님
    "paths": {
      "common/*": ["../common/src/*"] // common 모듈을 common/src에서 찾도록 매핑
    }
  },
  "include": [
    "src/**/*.ts"
  ],
  "references": [
    { "path": "../common" }
  ]
}

예시의 버전 조건도 확인합니다. 위 baseUrl 설정은 기존 5.x 프로젝트의 해석 방식을 설명하기 위한 것입니다. TypeScript 6.0에서는 폐기 예정 옵션이므로 새 설정은 이를 생략하고 paths에 ../common/src/* 같은 명시적 상대 경로를 적을 수 있습니다. module: "esnext"만 보고 어떤 런타임에서나 같은 해석이 된다고 단정하지 않고, moduleResolution도 실행 도구에 맞춥니다.

이제 ui 프로젝트의 소스 코드에서 import { MyType } from 'common/types';와 같이 임포트할 수 있습니다. (./src/types/index.ts에 있다면 common/types로 임포트)

모노레포에서의 타입 가져오기

ui 프로젝트에서 common 프로젝트의 타입을 가져오는 방법은 두 가지입니다.

references와 paths는 출력 import를 다시 쓰지 않습니다. 타입 검사·빌드 순서·실제 모듈 해석을 나누어 확인합니다.

주의사항 및 고려사항

• composite: true의 영향: composite 프로젝트는 선언 출력과 모든 구현 파일의 include/files 포함 조건을 만족해야 합니다. noImplicitAny를 자동으로 강화하는 옵션은 아닙니다.
• 순환 의존성: 프로젝트 레퍼런스는 순환 의존성을 허용하지 않습니다. 만약 A가 B에 의존하고 B가 A에 의존하는 순환 의존성이 발생하면 빌드 오류가 발생합니다. 이는 아키텍처 문제를 진단하는 데 도움이 됩니다.
• 번들러와의 통합: tsc --build는 각 프로젝트를 개별적으로 컴파일하고 .js 파일을 생성하지만, 최종적으로 이들을 하나로 묶는 것은 여전히 웹팩, Vite, Rollup과 같은 번들러의 역할입니다. 번들러 설정에서도 paths 매핑 등을 동일하게 구성해야 합니다.
• solution tsconfig.json: 모든 하위 프로젝트를 포함하고 빌드를 조정하는 최상위 tsconfig.json을 "Solution tsconfig.json"이라고 부르기도 합니다.

프로젝트 레퍼런스는 대규모 타입스크립트 프로젝트와 모노레포에서 하위 프로젝트 간 의존성을 명시하고 증분 빌드를 가능하게 하는 기능입니다.

각 하위 프로젝트의 독립성을 유지하면서 타입 안전한 의존 관계를 구성할 때 사용합니다.

선언이 없는 첫 빌드부터 추적합니다. 다음은 위 ui → common 구조에 실제 소스를 채운 사례입니다. packages/common/src/types.ts와 packages/ui/src/button.ts의 내용은 아래와 같고, 다른 구현 파일이나 package.json은 없습니다. 두 하위 설정의 target, rootDir, outDir, strict, composite는 앞 예시 그대로 두되, 이번 사례에서는 각각 module: "Node16", moduleResolution: "Node16", types: [], noEmitOnError: true를 명시합니다(TypeScript 4.7 이상). common의 declaration과 declarationMap도 그대로 유지합니다. 별칭 설정 대신 다음의 상대 타입 import를 사용합니다.

export interface CommonType { label: string; }

import type { CommonType } from "../../common/src/types";
export const button: CommonType = { label: "save" };

루트는 빌드 순서를 배열 순서로 외우지 않도록 다음처럼 일부러 ui를 먼저 적었습니다. 초기 dist·.tsbuildinfo가 전혀 없는 새 프로젝트에서 시작합니다.

{
  "files": [],
  "references": [
    { "path": "./packages/ui" },
    { "path": "./packages/common" }
  ]
}

1. 최초에 tsc -p packages/ui만 실행하면 common을 먼저 빌드할까요? 편집기에서 타입이 보인다는 사실만으로 명령행 검사도 통과한다고 판단해도 될까요?
2. 이어서 루트의 tsc -b를 실행하면 두 프로젝트 중 무엇이 먼저 빌드되나요? ui의 JavaScript에 위 타입 import가 남나요? 아무 파일·옵션·산출물도 바꾸지 않은 두 번째 tsc -b는 다시 모든 파일을 출력해야 할까요?
3. 정상 첫 빌드 후 common의 label: string만 label: number로 바꾸고 ui의 코드는 그대로 둔 채 다시 tsc -b를 실행합니다. 무엇이 실패하며 어떤 소스를 고쳐야 하나요? noEmitOnError를 켰는데도 이전 ui/dist가 남아 있다면 새 빌드가 통과했다는 증거일까요?