#Frontend

모노리포 희망편, 절망의 리포가 희망의 리포로 부활하기까지 걸린 1년

Summary

절망의 모노리포를 희망으로! 토스가 100명 규모의 의존성 파편화를 해결한 비결

Yarn/pnpm 카탈로그 기능을 활용한 프론트엔드 플랫폼의 혁신적 의존성 단일화 여정

토스 프론트엔드 플랫폼 팀이 모노리포 확장 과정에서 겪은 의존성 파편화 문제를 슬기롭게 극복한 1년간의 기록입니다. 폴리리포로 쪼개는 손쉬운 타협 대신, 모노리포의 강점을 유지한 채 핵심 버전을 표준화하는 카탈로그 전략을 구축하여 엄청난 성능 향상과 일관된 DX를 동시에 쟁취했습니다. 대규모 코드베이스를 안정적이고 쾌적하게 유지하고자 하는 플랫폼 엔지니어들의 땀방울이 담긴 실전 가이드를 만나보세요.

01모노리포 규모 확장 시 마주하게 되는 의존성 트리 파편화와 빌드 저하 문제 분석
02폴리리포 전환 대비 모노리포를 고수하며 최신 환경을 전파하는 아키텍처적 당위성
03Yarn 및 pnpm의 카탈로그(Catalog) 프로토콜을 이용한 핵심 라이브러리 표준 버전 강제화
04안정적인 버전 마이그레이션을 돕는 점진적 릴리즈 전략과 AI Skill 도구 연계
05의존성 맵 크기 84% 절감 및 전체 설치 속도 52% 단축이라는 독보적인 최적화 지표

RECOMMENDATION

수십 명 이상의 개발자가 하나의 모노리포에서 협업하며 패키지 버전 파편화로 피로감을 느끼고 있거나, 공통 라이브러리의 배포 규격과 속도를 안전하게 관리하고 싶은 플랫폼 빌더들에게 카탈로그 도입을 강력히 권장합니다.

The Problem

토스 프론트엔드 조직이 대규모로 확장되면서 모노리포 내 각 서비스가 사용하는 라이브러리 버전이 파편화되었고, 이로 인해 개발 서버 실행 지연, 의존성 설치 시간 증가, 플랫폼 공통 라이브러리 업데이트의 높은 비용과 신뢰성 저하 문제가 발생했습니다.

The Solution

Yarn 및 pnpm 패키지 매니저의 카탈로그(Catalog) 기능을 도입하여 핵심 라이브러리 버전을 모노리포 전체 수준에서 통일하고, 파괴적 변경에 대응하기 위한 자동 코드 변환 스크립트와 AI Skill을 개발하여 배포했습니다.

The Result

의존성 정보를 기록하는 .pnp.cjs 파일 크기가 96MB에서 15MB로 84% 감소했으며, 개발 서버 실행 속도는 약 23%(26.7초에서 20.3초), 전체 의존성 설치 시간은 약 52%(528.4초에서 249.9초) 단축되는 정량적 성과를 거두었습니다.

Trade-off

기존 서비스를 카탈로그 체계로 마이그레이션하기 위해 서비스 담당 개발자들과 직접 소통하며 오프라인으로 정합성을 검증하는 초기 리소스가 크게 소요되었으며, 라이브러리 버전을 수동으로 점진 마이그레이션해야 하는 추가적인 관리 공수가 수반됩니다.

Key Concepts

Concept · 01

모노리포 (Monorepo)

여러 프로젝트나 서비스의 소스 코드를 분리하지 않고 단 하나의 저장소(Repository)에서 통합하여 관리하는 소프트웨어 개발 방식입니다. 코드 공유가 극도로 간편해지고 개발 표준을 맞추기 용이한 장점이 있습니다.

토스의 모든 모바일 제품 개발 코드와 데스크톱 제품 코드를 각각 1개의 모노리포로 통합하여 운영하고 있습니다.

Concept · 02

카탈로그 (Catalog)

pnpm이나 Yarn 같은 최신 패키지 매니저에서 지원하는 기능으로, 모노리포 루트 환경 설정에 표준 의존성 버전을 정의하고 개별 프로젝트는 프로토콜을 통해 이를 참조하게 만드는 관리 도구입니다.

pnpm-workspace.yml 또는 .yarnrc.yml 파일에 표준 라이브러리 버전을 정의하여 개별 서비스가 동일 버전을 바라보도록 제어했습니다.
React, Next.js, TypeScript, TDS 등 핵심 의존성 10~20개를 카탈로그에 편입시켜 파편화를 원천 차단했습니다.

Concept · 03