멀티 프로젝트를 모노레포로 전환 후기

신규 프로젝트의 경우 코드 스타일과 공통 기능에 대한 설계를 미리 작성하여 모노레포를 선도입해서 사용해왔습니다. 하지만 이번에는 조금 다른 상황이었습니다. 기존에 멀티 프로젝트로 나뉘어 운영되던 서비스들을 모노레포 구조로 변경하는 작업을 진행했고, 그 과정과 결과를 공유하고자 합니다.

멀티 프로젝트를 사용했던 이유

초기에는 개발 담당자들이 각자의 서비스를 개발하다 보니 자연스럽게 각각의 레포지토리에서 관리를 진행했습니다. 당시에는 이것이 가장 자연스러운 선택이었죠.

하지만 프로젝트가 커지고 작업을 진행하다보니 불편해지기 시작했습니다. 무엇보다 관리차원에서 너무 힘들어지기 시작했습니다.

 

1. 일관성 부족

• 프로젝트마다 다른 코드 컨벤션
• 각기 다른 코드 패턴
• 매번 새롭게 디자인 시스템을 재도입해야 하는 번거로움

2. 관리의 어려움

• 프로젝트별로 다른 의존성 버전
• 각각 별도의 트러블슈팅 필요
• 새로운 프로젝트 파악에 소요되는 시간 증가

3. 서비스 확장

• 기존 서비스에서 독립된 성격을 가진 새로운 프로덕트 발생

이러한 문제들로 인해 개발 효율성이 떨어지고, 유지보수 비용이 증가하는 상황에 직면했습니다.

 

모노레포 도입 전략

모든 프로젝트를 한 번에 묶어버리면 오히려 더 큰 문제가 발생할 수 있다고 판단했습니다.

가장 큰 문제는 배포 시스템의 복잡도가 올라갈 것으로 판단하였고 추가적으로는 커밋 히스토리에 대한 파악이 어려울 것이라고 판단하였습니다.

• 도메인이 다른 프로젝트를 묶을 경우: 브랜치 관리, 커밋 메시지 관리의 복잡성 증가
• 배포 시스템의 복잡도 증가: 각 프로젝트마다 dev, prod 브랜치를 분리해서 운영하는 상황에서 모든 프로젝트를 하나로 묶으면 test1-dev, test1-prod, test2-dev, test2-prod 등으로 배포 복잡도가 기하급수적으로 증가

그래서 도메인 기반으로 프로젝트들을 그룹핑하여 진행하여 모노레포의 장점과 배포 시스템의 복잡도가 올라가지 않도록 도입 전략을 작성했습니다.

도메인 기반 모노레포

따라서 같은 도메인을 가진 프로젝트들을 묶는 방식으로 모노레포를 도입하기로 결정했습니다.

AS-IS: 멀티 레포지토리

• 서비스 (Next.js)
• 어드민 (React)

TO-BE: 도메인별 모노레포

• 서비스 (Next.js)
• 어드민 (React)
• 플러그인 서비스 (React) - 기존 서비스에서 분리된 독립 서비스

프로젝트 구조

프로젝트

공통 패키지

monorepo/
├── packages/           # 공통 패키지
│   ├── eslint/
│   ├── prettier/
│   ├── tailwind/
│   ├── utils/
│   └── typescript/
├── apps/
│   ├── service/        # Next.js 서비스
│   ├── admin/          # React 어드민
│   └── plugins/        # React 플러그인 서비스
└── package.json

패키지 관리 전략

• 공통 패키지: 서비스에서 공통으로 사용하는 컴포넌트, 유틸리티, 타입 등
• 선택적 사용: 각 서비스에서 필요하지 않은 패키지는 제외 가능
• 단순한 Git Flow: dev, prod 브랜치로만 전략 구성

결과 및 개선사항

1. 커밋 히스토리 관리 개선

같은 도메인 성격을 가진 프로젝트들의 묶음이다 보니 커밋 히스토리 관리가 훨씬 체계적으로 이루어졌습니다.

 

2. 배포 시스템 단순화

• 각 프로젝트별 배포 시스템을 하나의 도메인 배포 시스템으로 통합
• CI/CD 파이프라인에서 각 서비스의 CI가 병렬로 실행되도록 구성
• 배포 부담 대폭 감소

3. 코드 품질 향상

전체 프로젝트에 통일된 코드 컨벤션 규칙을 적용하여 사이드 이펙트 발생 문제가 해결되었습니다.

 

4. 의존성 관리 효율화

• 공통 라이브러리를 최상단에서 관리
• 모든 패키지의 버전을 통일하여 관리
• 의존성 충돌 문제 해결 및 업데이트 작업 간소화

마무리

모노레포 전환 작업을 통해 개발 효율성과 유지보수성을 크게 개선할 수 있었습니다.

특히 도메인별로 모노레포를 구성하는 전략이 핵심이었습니다. 무작정 모든 프로젝트를 하나로 묶었을 때, 배포 시스템이 너무 무거워질 문제가 발생할 것으로 판단하여 비즈니스 도메인과 기술적 특성을 고려한 합리적인 그룹핑이 프로젝트를 개선하는데 성공했다고 보여집니다.