목차
업데이트 부담을 낮춘 토스 프론트엔드 모노리포의 카탈로그 (2026-08)
원문 정보
- 원문: 모노리포 희망편, 절망의 리포가 희망의 리포로 부활하기까지 걸린 1년
- 매체 · 게시일: 토스 기술 블로그 · 2026-08-10
- 저자: 박서진 (토스 클라이언트 엔지니어링 헤드), 박성범 (프론트엔드 플랫폼 엔지니어)
- 원문 내용을 바탕으로 재구성한 요약입니다.
ATM 현금 찾기와 행운복권 사이의 React 버전
같은 토스앱 안에서도 ATM 현금 찾기와 행운복권은 서로 다른 React 버전을 썼습니다. React만의 문제도 아니었습니다. 컴포넌트 라이브러리 TDS, 상태 관리 라이브러리 Jotai, TypeScript와 ESLint처럼 개발에 쓰는 주요 라이브러리가 10~20개 정도였고, 서비스마다 선택한 종류와 버전이 달랐습니다.
토스 프론트엔드는 5명일 때부터 모노리포를 사용해 왔습니다. 코드를 모아 둔 역사는 길었습니다. 그런데 2025년 초에는 개발자 수가 지금보다 훨씬 적었는데도 의존성 설치에 캐시가 있어도 1분 이상 걸리곤 했습니다. 최신 환경을 쓰는 서비스에서는 개발 서버가 빨리 뜨고 새로운 React API도 쓸 수 있었지만, 오래전에 만든 서비스에서는 개발 경험까지 낡은 채로 남았습니다.
공통 라이브러리를 만드는 쪽도 어려웠습니다. 한 서비스에서 잘 동작한 코드가 다른 서비스에서도 동작하리라고 보장하기 어려울 만큼 검증해야 할 환경이 다양했기 때문입니다. 서비스 개발자는 업데이트했다가 문제가 생길까 봐 새 버전을 꺼렸습니다. 플랫폼은 변경하기 어렵고 서비스는 업데이트하기 어려워, 오래된 의존성이 그대로 남는 상황이었습니다.
리포를 서비스별로 쪼개는 폴리리포도 검토했습니다. 각 리포를 가볍게 만들면 의존성이 많아서 생기는 설치 지연은 줄일 수 있는 선택입니다. 하지만 플랫폼 팀은 서비스마다 다른 개발 환경과 공통 코드의 높은 변경 비용은 남고, 파편화는 더 심해질 것으로 봤습니다. 계속 플랫폼을 개선하고 그 변경을 서비스에 전파하려면, 리포를 나누는 것만으로는 부족했습니다.
그래서 서비스가 쓰는 핵심 라이브러리의 버전을 맞추기로 했습니다. 버전 선택을 제한해도 괜찮을지는 걱정거리였습니다. 실제 개발자들을 관찰하니 대부분은 React나 Jotai가 필요하다는 결정을 했고, 특정 버전을 지정해야 하는 경우는 거의 없었습니다. 플랫폼 팀은 이 관찰을 바탕으로 서비스가 참조할 표준 버전을 제공하기로 했습니다.
서비스의 기본값이 된 카탈로그
토스가 권장하는 표준 라이브러리 버전 묶음이 카탈로그입니다. pnpm과 Yarn도 같은 이름의 기능을 제공합니다. 모노리포의 pnpm-workspace.yml 또는 .yarnrc.yml에 버전을 정의하면, 서비스는 직접 버전을 적는 대신 catalog: 프로토콜로 참조합니다. 패키지 매니저가 그 정의에 맞춰 의존성을 설치합니다.
카탈로그에는 이름도 붙일 수 있습니다. 예를 들어 안정적인 버전 묶음을 stable, 실험적인 묶음을 beta로 정의하면 서비스에서 사용할 묶음을 지정하는 방식입니다.
catalogs:
stable:
react: ^18.2.0
beta:
react: ^19.1.0
# 서비스 package.json
"react": "catalog:stable"토스는 React, Next.js, TypeScript, TDS, 토스 앱 SDK처럼 서비스 개발에 필수인 라이브러리부터 카탈로그에 넣었습니다. 설치 경로도 바꿨습니다. 새 서비스를 스캐폴딩하면 최신 카탈로그를 참조하고, 카탈로그에 포함된 라이브러리를 yarn add로 추가하면 해당 서비스가 이미 쓰는 카탈로그를 참조합니다. 직접 설치할 때마다 라이브러리의 최신 버전을 가져오는 방식과는 다릅니다. 카탈로그를 참조해야 하는데 빠뜨린 경우는 CI에서 잡습니다.
가장 어려운 작업은 기존 서비스의 전환이었습니다. 서비스 코드 오너들과 오프라인으로 모여 실제 동작을 하나씩 확인하면서 의존성이 카탈로그를 참조하도록 바꿨습니다. 이 과정을 거쳐 모든 서비스에 카탈로그를 적용했습니다.
파괴적 변경을 구분하는 발행 연월
카탈로그를 공유하면 버전 변경의 영향도 함께 퍼집니다. 이미 발행한 카탈로그에서 패키지를 함부로 1.0.0에서 2.0.0으로 올리면, 해당 카탈로그를 쓰는 서비스는 업데이트를 선택하지 않았는데도 하위 호환성을 깨는 파괴적 변경에 대응해야 합니다.
토스는 카탈로그 이름에 발행 연월을 넣습니다. stable-26.07, stable-26.08 같은 이름입니다. 한 번 발행한 카탈로그 안에서는 패키지 버전을 바꾸더라도 파괴적 변경을 포함해서는 안 됩니다. 파괴적 변경으로 메이저 버전을 올려야 한다면 새 카탈로그를 발행합니다. 서비스 개발자는 카탈로그 이름이 바뀌는 시점에 파괴적 변경의 가능성이 있다는 점을 알 수 있습니다.
발행 빈도에도 제한을 뒀습니다. 서비스가 파괴적 변경에 너무 자주 대응하지 않도록 새 카탈로그는 한 달에 최대 한 번만 발행합니다. 사내 패키지 메인테이너들은 매월 초 모여 예정된 변경을 논의하고, 하나 이상의 패키지에 파괴적 변경이 있으면 그달에 새 카탈로그를 냅니다. 이때 기존 코드를 자동으로 변환하는 스크립트를 항상 함께 제공합니다.
검증도 발행의 조건입니다. 카탈로그에 넣은 라이브러리는 주요 사용 사례를 다루는 테스트 페이지를 만들고, 수정하거나 릴리즈하기 전에 확인합니다. 카탈로그로 관리하는 패키지는 릴리즈 전에 적어도 한 개 이상의 서비스에서 동작을 검증해야 합니다. 새 카탈로그도 일부 서비스에서 먼저 테스트하고, 안정성을 확인한 뒤 각 서비스가 수동으로 마이그레이션하도록 했습니다.
카탈로그 정책을 코드로 옮긴 Yarn 플러그인
서비스에서 마이그레이션을 진행하되, 코드까지 일일이 고치게 두지는 않았습니다. 플랫폼 팀은 업그레이드에 필요한 코드 수정 스크립트와 AI Skill을 만들어 배포했습니다. 자체 CLI도 제공합니다. yarn catalog switch stable-26.08 path/to/service를 실행하면 서비스가 참조하는 카탈로그를 바꾸고 코드도 자동으로 마이그레이션합니다.
자체 Yarn 플러그인 yarn-plugin-catalogs는 기본 카탈로그 기능을 확장합니다. 예를 들어 TypeScript 7.0.0을 쓰는 stable-26.07을 바탕으로 일부 서비스에서 TypeScript 7.0.2-rc를 미리 시험하고 싶다면, stable-26.07/canary를 발행하는 방식입니다. 이렇게 정의한 확장 문법은 catalogs.yml에 작성하고, yarn catalogs apply 명령으로 Yarn 공식 카탈로그 문법으로 변환합니다.
특정 워크스페이스에서 카탈로그를 반드시 사용하게 하거나 사용하지 못하게 제한하는 기능도 있습니다. 모노리포 전반에 적용할 정책을 개발 도구가 검사하고 실행하도록 만든 것입니다.
오래된 제품까지 같아진 개발 환경
카탈로그를 100% 적용한 뒤에는 설치해야 할 의존성의 개수가 물리적으로 줄었습니다. 같은 라이브러리도 서비스마다 서로 다른 버전을 쓰면서 늘어났던 의존성을 줄인 결과입니다. 의존성 정보를 기록하는 Yarn PnP(Plug’n’Play)의 .pnp.cjs 파일은 96MB에서 15MB로 약 84% 작아졌습니다. 모노리포 전체 의존성 설치 시간은 약 52%, 개발 서버 실행 시간은 약 23% 줄었습니다.
카탈로그 적용 전후 수치
| 항목 | 적용 전 | 적용 후 |
|---|---|---|
.pnp.cjs 파일 크기 | 96MB | 15MB (약 84% 절감) |
| 개발 서버 실행 시간 | 26.7초 | 20.3초 (약 23% 개선) |
| 모노리포 전체 의존성 설치 시간 | 528.4초 | 249.9초 (약 52% 감소) |
서비스 개발자가 의존성을 믿고 업데이트할 근거도 생겼습니다. 카탈로그의 패키지는 다른 서비스에서 먼저 검증한 버전입니다. 플랫폼 팀은 패키지 사이의 의존 관계도 확인합니다. 예를 들어 A 패키지가 B 패키지 v1에 의존하는데 서비스에서 B 패키지 v2를 선택하면 A가 잘못 동작할 수 있습니다. 카탈로그 안의 버전과 의존 관계를 함께 검증하면 이런 불일치를 예방할 수 있습니다.
어떤 서비스가 어떤 패키지 버전을 쓰는지 보이자, 패키지 개발자가 변경의 영향을 파악하기도 쉬워졌습니다. 기존 아키텍처나 인터페이스를 개편할 때의 부담이 줄었습니다. 토스 프론트엔드 챕터는 지난 하반기에 RSC, TypeScript 7, Rspack, E2E 테스트 같은 큰 개선을 빠른 기간에 안정적으로 시도했습니다. 공급망 공격으로 서드파티 패키지에 보안 문제가 생겼을 때도 패치 버전을 카탈로그에 적용해 신속히 대응했습니다.
이제 토스에서는 100명이 넘는 프론트엔드 엔지니어가 하루에 수백 번 제품을 업데이트하면서도 핵심 개발 환경을 같게 유지합니다. 오래된 제품도 예외는 아닙니다. 모두 최신에 가까운 동일 버전의 React 19와 Next.js 15를 쓰고, 모든 서비스가 Go로 작성된 TypeScript 7을 사용합니다. 번들러와 Linter 경험도 같습니다. 공통 코드를 만들 때 여러 React 버전을 고려하던 부담이 줄어 서비스 간 코드 공유도 쉬워졌습니다.
사내 패키지까지 모인 또 하나의 모노리포
서비스에 카탈로그가 자리 잡은 뒤에는 사내 패키지의 관리 방식도 바꿨습니다. 모든 모바일 제품 코드는 모노리포 하나에 있고 데스크톱 제품도 비슷하게 관리했지만, 사내 패키지는 폴리리포로 흩어져 있었습니다. 어떤 패키지가 있는지, 잘 관리되고 있는지, 누가 관리하는지 파악하기 어려운 상태였습니다.
토스는 흩어진 사내 패키지를 하나씩 모아 패키지 모노리포를 만들었습니다. 이곳에는 매니페스트와 설정을 검사하는 패키지 린트 도구가 있습니다. PR에 파괴적 변경이 포함되면 메이저 버전 업데이트를 권고하는 검사기도 갖췄습니다. 플랫폼 팀이 만든 패키지 개발 도구와 E2E 테스트 환경, 릴리즈 워크플로우를 함께 마련해 카탈로그에 포함된 패키지를 관리합니다.