Monorepo란
Monorepo는 여러 프로젝트나 패키지를 하나의 단일 버전 관리 저장소(repository)에서 관리하는 개발 전략이다.
반대 개념은 Polyrepo로, 각 프로젝트별로 별도의 저장소를 두는 방식이다.
repo(repository): 버전 관리 저장소. git과 같은 버전 관리 시스템에서 코드의 변경 이력, 브랜치, 커밋 등을 추적·저장하는 공간이다.
Polyrepo에서 Monorepo로 넘어간 이유
Polyrepo의 문제점을 해결하기 위해서다. 여러 팀이 여러 저장소를 운영하다 보면 다음 문제가 발생한다.
1. 의존성 지옥
공통 라이브러리를 수정하면, 이를 사용하는 모든 저장소에 일일이 버전을 올리고 배포해야 한다. 10개의 레포가 같은 내부 라이브러리를 사용하면 10번 반복 작업이 필요하다.
2. 코드 공유의 어려움
유틸함수, 공통 컴포넌트 등을 재사용하려면 npm 패키지로 만들거나 복사/붙여넣기를 해야 했다.
- 복사 붙여넣기는 코드 불일치를 낳고
- 패키지 배포는 번거롭다
3. 일관성 없는 도구와 설정
레포마다 ESLint, TypeScript, 테스트 설정이 달라 팀 간 협업이 어려워진다.
4. 변경 영향 파악 어려움
A 레포의 변경이 B, C 레포에 어떤 영향을 주는지 사전에 알기 어렵다.
Monorepo가 제공하는 해결책
| 문제 | Monorepo의 해결 |
|---|---|
| 의존성 관리 | 모든 패키지가 같은 저장소 → 한 번에 변경과 확인이 가능 |
| 코드 공유 | 공통 코드를 패키지로 즉시 참조, 배포 없이 공유 |
| 일관성 | 하나의 Lint, 빌드, 테스트 설정을 전체에 적용 |
| 원자적 커밋 | 여러 패키지에 걸친 변경을 단 하나의 커밋으로 가능 |
| 가시성 | 전체 코드베이스를 한눈에 파악 가능 |
단점
- 저장소 크기가 커질수록 git clone, CI 속도가 느려진다
- 도구 설정이 복잡해질 수 있다
- 권한 관리가 레포 단위로 되지 않아 접근 제어가 어렵다
Monorepo에서 도구 설정이 복잡해지는 이유
단일 프로젝트(Polyrepo)의 설정은 간단하다.
프로젝트A/
├── package.json
├── .eslintrc
├── tsconfig.json
└── jest.config.js
하나의 프로젝트이기에 설정 파일도 하나만 있으면 된다.
하지만 Monorepo는 여러 프로젝트가 한 곳에 있다.
모노레포/
├── apps/
│ ├── 웹앱/
│ │ ├── package.json
│ │ ├── .eslintrc ← 웹앱용 ESLint 설정
│ │ └── tsconfig.json ← 웹앱용 TS 설정
│ └── 모바일앱/
│ ├── package.json
│ ├── .eslintrc ← 모바일용 ESLint 설정 (웹이랑 달라야 함)
│ └── tsconfig.json ← 모바일용 TS 설정
└── packages/
├── 공통UI/
│ ├── package.json
│ ├── .eslintrc
│ └── tsconfig.json
└── 유틸함수/
├── package.json
├── .eslintrc
└── tsconfig.json
프로젝트마다 설정이 조금씩 달라져야 하는데, 그걸 관리해야 한다.
문제 1 — 공통 설정과 개별 설정을 나눠야 함
전체 공통 규칙 → 모든 프로젝트에 적용
웹앱 전용 규칙 → 웹앱에만 적용
모바일 전용 규칙 → 모바일에만 적용
이걸 겹치지 않게 잘 나눠야 한다.
문제 2 — 빌드 순서를 맞춰야 함
잘못된 순서:
웹앱 빌드 시작 → 공통UI가 아직 빌드 안 됨 → 오류!
올바른 순서:
공통UI 먼저 빌드 → 유틸함수 빌드 → 웹앱 빌드 → 모바일앱 빌드
프로젝트 간에 의존 관계가 있어서 순서를 맞춰야 한다.
문제 3 — 어디가 변경됐는지 파악해야 함
유틸함수만 수정했는데
→ 웹앱도 다시 빌드해야 하나?
→ 모바일앱도 다시 빌드해야 하나?
→ 공통UI는?
변경된 부분만 골라서 빌드/테스트해야 시간이 절약되는데, 이걸 파악하는 게 복잡하다.
Monorepo 전용 도구
그래서 이 복잡함을 해결하기 위한 전용 도구가 등장했다.
- Turborepo — 빌드 순서 자동 관리, 변경된 것만 빌드
- Nx — 대규모 Monorepo 관리 도구
- Lerna — 패키지 버전 관리
여러 프로젝트가 한 곳에 있다 보니 설정, 빌드 순서, 변경 감지 등을 각각 + 전체로 동시에 관리해야 해서 복잡해지는 것이다.