Reference QA

프로젝트 참조는 네 설정을 함께 맞춘다

모노레포에서 타입을 안정적으로 가져오려면 생산자, 소비자, 루트 빌드, 경로 해석이 같은 방향을 가리켜야 합니다. 한 곳만 맞아도 전체 참조는 쉽게 흔들립니다.

생산자 composite, declaration

소비자 references, paths

루트 tsc -b가 전체 순서를 조정한다.

검증 축	필수 설정	통과 신호	깨질 때 증상
생산자 프로젝트 다른 패키지가 타입을 읽는 대상	`composite: true`, `declaration: true`	`dist`와 `.d.ts`가 함께 생성된다.	소비자가 소스 파일을 직접 훑거나 타입을 찾지 못한다.
소비자 프로젝트 타입을 가져와 사용하는 패키지	`references`가 생산자 폴더를 가리킨다.	생산자가 먼저 빌드되고 소비자 타입 검사가 이어진다.	빌드 순서가 뒤집히거나 변경분이 증분 빌드에 반영되지 않는다.
경로 해석 import 이름과 실제 폴더 연결	`paths`와 번들러 alias가 같은 대상을 본다.	`common/types` 같은 패키지식 import가 동작한다.	타입은 맞는데 런타임 번들이 다른 파일을 읽는다.
루트 솔루션 전체 빌드 그래프를 시작하는 파일	`files: []`와 하위 프로젝트 목록	`tsc -b`가 그래프 순서대로만 실행된다.	루트가 직접 소스를 컴파일하거나 순환 참조를 늦게 발견한다.

약한 경계 소스 파일 직접 참조

import { CommonType } from "../../common/src/types";

권장 경계 컴파일된 선언 파일 참조

import { CommonType } from "common/types";

검증 순서 생산자 산출물부터 확인한다

.d.ts가 없으면 소비자는 안정적인 타입 경계를 읽을 수 없습니다. 먼저 산출물이 생기는지 확인합니다.

설계 기준 참조 방향은 아키텍처 방향이어야 한다

빌드가 빠른지만 보지 말고, 소비자가 생산자를 참조하는 방향이 실제 패키지 의존성과 일치하는지 확인합니다.