토스 모노리포가 100명 규모에서도 굴러가는 이유: 카탈로그
개요
- 토스는 100명 이상의 프론트엔드 엔지니어가 하루 수백 번 배포하면서도, 모든 서비스가 동일한 버전의 React 19 / Next.js 15 / TypeScript 7(Go 재작성 버전)을 사용함
- 모든 모바일 제품 코드는 1개의 모노리포로 통합되어 있으며, 이 일관성의 핵심에 '카탈로그(Catalog)' 가 있음
모노리포만으로는 해결되지 않았던 문제
- 5명 시절부터 모노리포를 써왔지만, 규모가 커지며 서비스마다 의존성 버전이 제각각이 됨 → 개발 경험 파편화
- 의존성 종류가 너무 많아 캐시가 있어도 설치에 1분 이상 소요됨
- 플랫폼 팀은 전사 공통 라이브러리를 만들어도 "한 곳에서 되면 다른 곳에서도 된다"를 보장할 수 없었고, 서비스 개발자는 업데이트 비용이 높아 낡은 의존성에 고착됨
폴리리포 전환은 답이 아니라고 판단
- 리포를 쪼개면 리포당 의존성이 가벼워지는 효과는 있지만, 파편화·공통 코드 비용 문제는 그대로 남고 오히려 심해질 것으로 판단함
- 문제의 본질은 "모노리포 구조"가 아니라 "서비스마다 의존성 버전이 다르다" 는 것이었음
- 실제 서비스 개발자를 관찰해보니 "React가 필요하다"는 결정은 해도, 특정 버전을 지정해야 하는 경우는 거의 없었음 → 표준 버전 제공이 가능하다고 결론
카탈로그 도입
- pnpm/Yarn의 catalog 기능을 활용해 표준 라이브러리 버전을 중앙 정의하고, 각 서비스는 "react": "catalog:" 프로토콜로 참조하는 방식
- React, Next.js, TypeScript, TDS(사내 컴포넌트), 토스 앱 SDK 등 핵심 라이브러리 10~20개부터 시작함
- 신규 서비스 스캐폴딩 시 카탈로그 참조가 기본값이고, yarn add도 카탈로그를 참조하도록 했으며, CI에서 카탈로그 미사용을 자동 검출함
- 기존 서비스는 코드 오너들과 오프라인으로 모여 동작을 검증하며 100% 마이그레이션함
정량적 효과
- Yarn PnP의 .pnp.cjs 파일 크기: 96MB → 15MB (약 84% 절감)
- 개발 서버 실행 속도: 26.7초 → 20.3초 (약 23% 개선)
- 캐시 없이 전체 의존성 설치 시간: 528.4초 → 249.9초 (약 52% 단축)
정성적 효과
- 카탈로그 패키지는 릴리즈 전 최소 1개 이상의 서비스에서 검증한다는 제약을 두어, "검증된 의존성"이라는 신뢰가 생김
- 패키지 간 의존 관계의 무결성을 플랫폼 팀이 검증해 버전 불일치로 인한 오동작을 예방함
- 의존성 가시성이 확보되자 패키지 개발자가 두려움 없이 구조 개편을 추진할 수 있게 됨 → RSC, TypeScript 7, Rspack, E2E 테스트 같은 급진적 개선을 짧은 기간에 안정적으로 도입함
- 공급망 공격 등 보안 이슈 발생 시에도 카탈로그에 패치 버전만 반영하면 전 서비스에 신속 대응 가능함
운영 정책이 핵심
- 카탈로그는 stable-26.08처럼 발행 연월로 버저닝하며, 이미 발행된 카탈로그에는 절대 파괴적 변경을 넣지 않음
- 새 카탈로그는 한 달에 최대 1회만 발행하고, 매월 초 사내 패키지 메인테이너들이 모여 예정된 변경 사항을 논의함
- 파괴적 변경이 있으면 항상 자동 코드 변환 스크립트(codemod)와 AI Skill을 함께 제공함
- yarn catalog switch stable-26.08 한 번으로 카탈로그 전환과 코드 마이그레이션이 자동으로 수행됨
- 자체 개발한 yarn-plugin-catalogs로 canary 카탈로그 발행(stable-26.07/canary), 특정 워크스페이스의 카탈로그 강제/제한 등 정책을 코드로 시행함
- 흩어져 있던 사내 패키지들도 별도의 패키지 모노리포로 통합해 린트 도구, 파괴적 변경 검사기, E2E 테스트, 릴리즈 워크플로우를 갖춤
결론
- 문제의 근원은 모노리포 구조 자체가 아니라, 일관된 정책을 광범위하게 전파할 수단과 가시성의 부재였음
- 카탈로그라는 기술 위에 월 1회 발행 정책, 정책 강제 도구, 정기 미팅, 패키지 모노리포라는 운영을 1년간 쌓아 올린 결과임
- 대규모 모노리포에서 문제를 겪고 있다면 폴리리포 전환 전에 먼저 문제를 명확히 정의해볼 것을 권함