Architecture
멀티레포에서
모노레포로
지속적으로 증가하는 컴포넌트 라이브러리의 유지보수 비용과 개발 효율성 저하 문제를 해결하기 위해,
26년도 연구 과제로 지정하며 105개의 컴포넌트 라이브러리를
멀티레포에서 모노레포로 전환한 과정과 결과를 공유합니다.
역할
프론트엔드 개발자
기간
2025년 12월 ~ 현재
부서 / 직급
개발센터 / 전임(대리)
Problem
어떤 문제가 있었죠?
내부 구조 노출
전역 스타일, 폰트, 사내 아이콘 등 공통 자산을 사용하기 위해 개별 모듈에서 라이브러리의 빌드 결과물인 "dist" 내부 경로에 직접 접근하고 있었습니다. 이는 라이브러리의 내부 폴더 구조가 변경될 때마다 참조 경로가 깨질 위험이 컸으며, 모듈 간의 강한 결합도를 유발했습니다.
트리쉐이킹 미지원
105개의 컴포넌트 전체가 하나의 번들로 묶여 불필요한 코드까지 포함됐습니다. 특정 모듈에서 단 15개의 컴포넌트만 사용하더라도 105개 전체 구성 요소와 연관 의존성을 모두 설치해야 했습니다.
의존성 버전 파편화
특정 버전부턴 멀티레포가 React 19로 업그레이드되면서 React 18 기반의 모듈들은 최신 컴포넌트를 사용할 수 없었습니다. 결국 버그 수정이나 기능 추가를 위해 과거 버전 브랜치를 별도로 유지하며 수동 배포를 반복해야 했습니다.
Overview
무엇이
달라졌죠?
Yarn Workspaces를 기반으로 모노레포를 선언하고, 캐싱이 지원되는 Nx로 빌드를 최적화했습니다. 버전 변경 이력 관리를 위해 Changesets을 도입해 릴리즈 프로세스를 체계화했습니다.
의존성 구조 변화
BEFORE — 멀티레포
@sprrow/components
단일 번들 · 트리쉐이킹 없음
v0.9.x
React 18
v1.0.x
React 19
서버 매니저
React 18
v0.9.123-compact
GUI
React 18
v0.9.123-compact
엔터프라이즈
React 19
v1.0.200
플러그인
React 19
v1.0.200
AFTER — 모노레포
@sp/monorepo
Yarn Workspaces · Nx · Changesets
atoms
공용
molecules
공용
organisms
공용
layout
공용
peerDependencies로 버전 위임
서버 매니저
React 18
GUI
React 18
엔터프라이즈
React 19
플러그인
React 19
Process
전환 여정기
인프라 및 폴더 구조 수립
Yarn Workspaces 기반 모노레포 환경을 선언하고, 빌드 성능 최적화를 위한 Nx와 자동화된 버전 관리를 위한 Changesets를 도입했습니다. Atomic Design 원칙을 적용해 atoms / molecules / layout / organisms 구조로 105개 컴포넌트를 재배치했습니다.
유연한 의존성 관리 전략
초기에는 dependencies로 의존성을 설정했으나 Changesets의 '버전 전파' 현상이 라이브러리 사용자가 하나의 컴포넌트를 업데이트할 때마다 의도치 않게 다른 컴포넌트들까지 상위 버전으로 마이그레이션해야 하는 관리 복잡성을 초래할 수 있음을 파악했습니다. 해당 이슈를 파트 내 공유하여 "호스트 모듈에 설치된 라이브러리를 공유하여 사용함으로써 버전 충돌을 방지하고 업데이트 효율을 높이자"는 리더의 기술적 조언을 수용해 peerDependencies에 의존성을 명시하도록 변경해 개별 컴포넌트의 독립적인 배포 유연성을 확보했습니다.
시맨틱 버저닝 규칙 수립
컴포넌트의 초기 버전은 1.0.0으로 정의하고, 기능 추가 시 Minor, 버그 수정 시 Patch를 업데이트하는 규칙을 제안 및 시행했습니다. 버전 전파 이슈 방지를 위해 리더와의 기술적 합의를 거쳐 Major 버전을 1.x.x 대에서 관리하는 전략을 채택했습니다.
트리쉐이킹으로 번들 최적화
라이브러리 경량화를 위해 ESM 문법 적용, 선택적 import, Rollup의 preserveModules: true, sideEffects: false 설정으로 트리쉐이킹을 구성했습니다. lodash를 lodash-es로 전면 교체하여 실제 사용되는 코드만 번들에 포함되도록 개선했습니다.
DX 도구 및 가이드라인 제공
새로운 환경 도입 시 동료들이 겪을 수 있는 초기 학습 비용을 최소화하고자 상세한 트러블슈팅 문서와 공유용 기술 가이드를 작성하고, 누락된 peerDependencies를 자동으로 탐색·설치하거나 전체 라이브러리를 한 번에 업데이트하는 커스텀 자동화 스크립트를 배포했습니다.
CI/CD 파이프라인
멀티레포 운영 당시의 로컬 수동 배포 방식은 배포 이력 공유 미흡으로 인한 버전 충돌이 빈번했습니다. GitLab CI/CD를 구축하여 원격 저장소 푸시 시 빌드 및 배포가 자동 수행되도록 개선하고, Discord 웹훅으로 배포 완료 알림을 연동했습니다.
품질 검증 체계
대규모 리뉴얼 제품의 품질을 보장하기 위해 Playwright를 활용한 시각적 회귀 테스트 환경을 구축했습니다. 모노레포 컴포넌트 적용 전후의 서버 화면을 정밀하게 캡처 및 비교하여 의도치 않은 UI 변경 사항을 사전에 검출하고 안정적인 릴리즈 기반을 마련했습니다.
Result
번들 사이즈
비교
모노레포 적용 전후, ERB 모듈의 실제 번들 사이즈 변화입니다.
−250KB
Parsed size 감소
Learned
배운 것들
단순히 일감을 받아 결과를 내는 것이 아닌, 과정 속에서 미래를 바라보며 다른 개발자도 내 코드를 손쉽게 이해하고 수정할 수 있도록 만드는 것이 목표였습니다.
불편함을 그냥 넘기지 않기
트리쉐이킹 미지원을 발견했을 때 개선 방법을 찾아 직접 적용했고, 수동 배포로 인한 버전 충돌 문제는 GitLab CI/CD 파이프라인과 Discord 웹훅 알림으로 해결해 배포 안정성을 확보했습니다.
공유와 협업의 힘
파트에 공유하면서 리더님의 한 마디, "명령어 하나로 peerDependencies까지 설치해 주세요"가 초기 설치 비용을 크게 줄였습니다. 또한 버저닝 수립에 대해 동료들과 고민하면서 제품에 맞는 전략을 만들어 낼 수 있었습니다.
문서화는 개발의 일부
내가 겪은 트러블슈팅을 문서로 남기면 다음 사람은 같은 시간을 낭비하지 않습니다. 또한 컨벤션과 적용법을 문서로 남겨서 동료들의 초기 진입 장벽을 낮추는 데도 신경 썼습니다.
Tech Stack
사용한 기술
빌드 & 번들링
Yarn Workspaces
모노레포 선언
Nx
캐싱 기반 빌드
Rollup
컴포넌트 번들링
ESM
트리쉐이킹 지원
릴리즈 관리
Changesets
버전 & 릴리즈 관리
GitLab CI/CD
자동 배포 파이프라인
협업 도구
Notion
파트 내 공유 문서
Jira
다른 부서와 공유
AI & 테스트
Claude Code
AI 코딩 어시스턴트
Playwright
UI 자동화 테스트