# [[Monorepo]]

## 📌 Brief Summary
모노레포(Monorepo)는 단일 Git 저장소 내에 여러 프론트엔드 애플리케이션, 공유 UI 컴포넌트 라이브러리, 디자인 토큰 및 공통 도구들을 함께 포함하여 관리하는 버전 관리 전략입니다 [1, 2]. 이는 단순히 코드를 한곳에 모아둔 모놀리식(Monolith) 구조가 아니라, 명확한 의존성 그래프와 공개 API(Public API)를 통해 패키지 간의 결합도를 낮추고 재사용성을 극대화하는 확장 가능한 프론트엔드 아키텍처입니다 [2-4].

## 📖 Core Content
- **구조 및 주요 특징:** 모노레포는 여러 앱(예: 웹, 관리자 앱, 모바일 웹)과 재사용 가능한 패키지(예: UI 키트, 디자인 토큰, API 클라이언트)가 하나의 공유된 히스토리와 일관된 의존성 그래프를 갖는 구조를 의미합니다 [1, 5]. 잘 구성된 모노레포는 높은 응집도(high cohesion)와 낮은 결합도(low coupling)를 갖춘 격리된 패키지 단위로 코드를 유지합니다 [2, 5].
- **도입의 장점:** 단일 저장소를 사용하면 UI 원시 컴포넌트(primitives), 디자인 토큰, 라우팅 규칙 등의 코드를 여러 앱에서 손쉽게 공유할 수 있습니다 [1, 6]. API 변경 시 해당 API를 소비하는 모든 앱의 업데이트를 한 번의 커밋으로 처리하는 원자적 리팩토링(atomic refactors)이 가능합니다 [1]. 기존처럼 코드를 공유하기 위해 여러 저장소에 걸쳐 다수의 풀 리퀘스트(PR)를 생성해야 하는 문제를 해결하여 개발 속도를 크게 향상시킵니다 [7]. 
- **필수 도구 생태계 (Tooling):** 2025년 기준 모노레포 환경을 지탱하는 주요 도구로는 `pnpm workspaces`, `Turborepo`, `Nx`, `Lerna` 등이 있습니다 [8, 9].
  - `pnpm workspaces`: 빠르고 공간 효율적이며 `workspace:*` 프로토콜을 통해 엄격하고 올바른 로컬 의존성 연결을 보장합니다 [10].
  - `Turborepo`: 증분 빌드(incremental builds)와 파이프라인 관리, 원격 캐싱 기능을 통해 로컬 개발 및 CI(지속적 통합) 속도를 비약적으로 높여줍니다 [11].
  - `Nx`: 강력한 프로젝트 그래프를 기반으로 코드 변경에 '영향을 받는(affected)' 프로젝트만 빌드 및 테스트하도록 최적화하며, 아키텍처 정책 강제성이 뛰어납니다 [12, 13].
- **확장성을 위한 경계(Boundaries) 규칙:** 성공적인 모노레포는 규율이 필요합니다. 내부 파일 경로로 직접 접근하는 '깊은 경로 임포트(deep imports)'를 엄격히 금지하고, 각 패키지가 `src/index.ts`와 같은 단일 진입점(Public API)을 통해서만 모듈을 노출하도록 구성하여 파일 간의 결합을 막아야 합니다 [4, 14]. 
- **아키텍처 방법론과의 결합:** 모노레포 내의 단일 공유 폴더(`shared/`)가 잡동사니 코드로 채워지는 문제를 방지하기 위해 Feature-Sliced Design (FSD)와 같은 방법론이 권장됩니다 [15-17]. FSD의 계층 구조(layers)를 모노레포의 패키지와 앱 내부에 적용하여, 어떤 모듈이 재사용 가능한지, 도메인 경계가 어디인지 예측할 수 있게 만듭니다 [16-20].

## 🔗 Knowledge Connections
- **Related Topics:** [[Turborepo]], [[Nx]], [[Feature-Sliced Design (FSD)]], [[Public APIs]]
- **Projects/Contexts:** [[Scalable Frontend Architecture]], [[Component Library Architecture]]
- **Contradictions/Notes:** 모노레포는 코드 통합 비용(integration cost)을 줄이고 원자적 변경을 가능하게 하지만, 경계 규칙 설정이나 CI 전략 같은 높은 규율이 요구됩니다. 반면, 앱들이 완전히 독립적인 릴리스 주기를 가지거나 컴플라이언스상 엄격한 보안 분리가 필요한 조직에서는 폴리레포(polyrepo) 접근 방식이 더 적합할 수 있습니다 [21, 22].

---
*Last updated: 2026-04-26*