[ 디자인 시스템 ] (0) 모노레포로 사내 라이브러리 만들기

모노레포 관리 가이드: 의존성부터 배포까지

모노레포 환경에서 디자인 시스템을 구축하며 마주했던 난관과 이를 극복하기 위해 수립한 해결 전략을 공유합니다. 의존성 제어부터 버전 관리 전략, CI/CD 파이프라인 구축까지 전체 여정을 다루는 시리즈의 첫 번째 글입니다.

왜 이런 구조가 필요했나

모노레포 도입 시 마주한 과제들

단일 저장소(Monorepo)에서 다수의 패키지로 구성된 디자인 시스템을 개발하다 보니 다음과 같은 현실적인 문제에 부딪혔습니다.

• 의존성 순환(Circular Dependency) - 패키지 간 참조 관계가 복잡해지면 의도치 않은 순환 참조가 발생할 위험이 큽니다.
• 버전 관리의 모호함 - 패키지 A를 수정했을 때 이를 의존하는 패키지 B와 C의 버전도 함께 올려야 하는지 판단 기준이 모호했습니다.
• 수동 작업으로 인한 휴먼 에러 - 의존성을 고려해 수동으로 버전을 올리는 과정에서 실수가 잦았습니다.
• 배포 프로세스의 비효율 - 릴리즈 때마다 태그를 생성하고 레지스트리에 배포하는 반복 작업은 생산성을 떨어뜨렸습니다.

해결 전략 파이프라인

모노레포 관리 워크플로우

1. 의존성 관리

ESLint Boundaries로 아키텍처 레이어 간 의존성 규칙 강제

↓

2. 버전 관리

Conventional Commits와 Changesets 조합으로 버전 자동 산정

↓

3. CI/CD 자동화

GitLab CI를 통한 정합성 검증 및 릴리즈와 배포 자동화

↓

4. 로컬 자동화

커스텀 스크립트(pnpm rel)로 릴리즈 브랜치 생성 간소화

핵심 기술 스택

도구	도입 목적 및 역할
ESLint Boundaries	상위 레이어가 하위 레이어를 참조하지 못하도록 린팅 레벨에서 차단
Changesets	변경된 패키지를 감지하여 버전 범위를 결정하고 CHANGELOG 자동 생성
Conventional Commits	커밋 메시지 규칙을 통해 버전 업데이트 타입(Major/Minor/Patch) 자동 결정
GitLab CI	MR 시점의 정합성 검증과 메인 병합 시 태그 생성 및 배포 파이프라인 수행
pnpm Workspace	심볼릭 링크 기반의 효율적인 모노레포 패키지 디펜던시 관리

배포 정책

📦 단일 패키지(Single Entry Point) 배포 전략

개발 편의성과 사용성을 고려해 @design-system/core 패키지만 Registry에 배포하는 전략을 택했습니다. 소비자(Consumer)는 core 패키지 하나만 설치하면 모든 기능을 사용할 수 있습니다. core 패키지가 내부의 개별 패키지들을 re-export 하는 구조이며 Tree-shaking을 지원하므로 실제 사용하지 않는 코드는 번들링 과정에서 제거됩니다.

빠른 시작 (Quick Start)

개발 워크플로우 예시

# 1. Feature 브랜치 생성 및 작업 시작
git switch -c feature/add-component

# 2. Conventional Commit 규칙에 맞춰 커밋 (Feat, Fix 등)
git commit -m "feat(components): add new Button variant"

# 3. develop 브랜치로 MR 생성 및 코드 리뷰 후 병합

# 4. 릴리즈 준비 (develop 브랜치)
git switch develop
pnpm rel          # 대화형 CLI로 버전 선택 → release 브랜치 자동 생성 및 푸시

# 5. GitLab에서 main 브랜치로 MR 생성 → 병합 승인
# → CI 파이프라인이 트리거되어 버전 태깅, Changelog 업데이트, 배포 자동 수행

주요 명령어

# 아키텍처 레이어 의존성 위반 검사
pnpm lint:layers

# 릴리즈 브랜치 생성 자동화 스크립트 실행
pnpm rel

# (수동 필요 시) Changeset 파일 생성
pnpm changeset

# (로컬 테스트용) 패키지 버전 일괄 업데이트
pnpm version-packages

시리즈 목차

본 가이드는 총 6개의 챕터로 구성되어 있으며 각 단계별 상세 설정과 노하우를 다룹니다.

순서	주제	내용 요약
01	모노레포 아키텍처	유지보수성을 고려한 레이어 기반 패키지 구조 설계
02	의존성 관리	ESLint Boundaries를 활용한 엄격한 의존성 규칙 적용
03	버전 관리전략	Changeset을 이용한 패키지 버전 동기화 및 관리
04	CI/CD 파이프라인	GitLab CI/CD를 통한 빌드, 검증, 배포 자동화 구현
05	자동화 스크립트	반복적인 릴리즈 작업을 줄여주는 DX(Developer Experience) 개선
06	트러블슈팅	구축 과정에서 겪은 주요 이슈들과 해결 방법 공유