4년차 SaaS 스타트업이 8개 멀티레포를 Turborepo 기반 모노레포로 전환한 실제 과정. Lerna 실패 이유, Turborepo 도입 결정, 전환 중 막힌 지점 3가지, 6개월 후 CI 빌드 72% 단축 결과까지.
8개의 분리된 레포지토리를 운영하던 한 SaaS 스타트업 개발팀이 Turborepo 기반 모노레포로 전환한 뒤 CI 빌드 시간을 72% 줄이고, 공유 컴포넌트 배포 사이클을 8개 PR에서 1개 PR로 압축했다. 이 글은 그 팀이 6개월 동안 겪은 시행착오와 실제 수치를 3인칭으로 정리한 케이스 스터디다.
멀티레포를 운영 중이고 빌드 속도 문제나 패키지 의존성 충돌로 고통받고 있다면, 또는 모노레포 전환을 고민하고 있다면 이 팀의 경험이 판단 기준이 될 수 있다.
이 스타트업은 창업 4년차에 접어든 B2B SaaS 팀이다. 제품은 하나지만 코드베이스는 여러 해에 걸쳐 8개의 독립 레포지토리로 쪼개졌다. 프론트엔드 앱 3개(고객용 웹, 관리자 대시보드, 내부 운영 툴), 백엔드 서비스 3개(API 서버, 인증 서비스, 알림 서버), 그리고 공유 UI 컴포넌트 패키지와 공유 유틸리티 패키지 레포 2개로 구성된 구조였다.
팀 규모는 개발자 12명. 각 레포마다 CI 파이프라인이 독립적으로 운영되고 있었고, 코드 리뷰 채널도 사실상 8개가 병렬로 돌아가고 있었다.
핵심 문제는 공유 패키지였다. 예를 들어 공유 UI 컴포넌트의 버튼 스타일 하나를 수정하면, 이를 사용하는 3개 프론트엔드 앱 각각에서 패키지 버전을 올린 PR을 따로 생성하고, 별도로 리뷰받고, 별도로 배포해야 했다. 단순 색상 변경 하나에 최소 4개의 PR이 필요했고, 팀원들은 "버튼 색 바꾸는 데 하루가 걸린다"는 말을 반복했다고 한다.
이 팀의 시니어 엔지니어는 당시 상황을 이렇게 표현했다. "코드는 하나의 제품인데, 저장소는 8개 회사처럼 운영되고 있었다."
팀이 특히 고통받은 지점은 두 가지였다. 첫째, 의존성 버전 드리프트. 공유 유틸리티 패키지가 세 가지 다른 버전으로 서로 다른 앱에서 사용되다 보니, 버그가 어느 버전에서 발생했는지 추적하는 데만 수 시간이 소요됐다. 둘째, CI 비용. 8개 파이프라인이 각각 전체 빌드를 수행하면서 월 CI 시간이 800분을 넘겼다.
팀은 2023년 초, 첫 번째 해결책으로 Lerna v3를 도입했다. 당시 팀 내에서 Lerna에 대한 경험이 있는 엔지니어가 있었고, 모노레포 전환 사례 자료도 Lerna 기반이 많았다. 마이그레이션은 약 3주 만에 완료됐고 팀은 기대감이 높았다.
그러나 문제는 곧 드러났다. Lerna의 의존성 호이스팅이 일부 패키지와 충돌을 일으켰다. 특히 두 개의 프론트엔드 앱이 동일 패키지의 서로 다른 버전을 필요로 하는 경우, 호이스팅이 예상과 다르게 작동하면서 런타임 에러가 발생했다.
더 큰 문제는 버전 관리였다. Lerna의 fixed 모드는 모든 패키지 버전을 동일하게 올려버렸고, independent 모드는 각 패키지 버전을 수동으로 관리해야 해서 12명의 팀에서 일관성을 유지하기 어려웠다. 결국 이 팀은 Lerna 도입 3개월 만에 재검토에 들어갔고, Turborepo로 방향을 바꿨다.
팀이 Turborepo를 선택한 이유는 세 가지로 정리된다.
팀은 6주짜리 마이그레이션 로드맵을 세웠다. 1~2주차에 레포 통합 및 pnpm-workspace.yaml 구성, 3~4주차에 turbo.json 파이프라인 설정 및 로컬 빌드 검증, 5~6주차에 CI 파이프라인 전환 및 Vercel Remote Cache 연결. 실제로는 7주가 걸렸다고 한다.
turbo.json — 이 팀이 사용한 기본 파이프라인 설정{ "$schema": "https://turbo.build/schema.json", "pipeline": { "build": { "dependsOn": ["^build"], "outputs": [".next/**", "!.next/cache/**", "dist/**"] }, "lint": { "outputs": [] }, "test": { "dependsOn": ["build"], "outputs": [] }, "dev": { "cache": false, "persistent": true } } }
모노레포 디렉토리 구조 (전환 후)monorepo/ ├── apps/ │ ├── web/ # 고객용 Next.js 앱 │ ├── admin/ # 관리자 Next.js 앱 │ └── api/ # Express API 서버 ├── packages/ │ ├── ui/ # 공유 UI 컴포넌트 │ ├── config/ # 공유 설정 (ESLint, TypeScript) │ └── utils/ # 공유 유틸 함수 ├── turbo.json └── pnpm-workspace.yaml
전환이 순조롭지만은 않았다. 팀이 실제로 막혔던 지점 세 가지는 다음과 같다.
React.FC 타입을 export할 때 Next.js App Router 환경에서 use client 지시어 없이 사용하면 TypeScript 타입 에러가 발생했다. 해결책은 패키지 진입점에 "use client"를 명시하거나, Server Component와 Client Component용 진입점을 분리하는 것이었다. 이 팀은 packages/ui/src/server.ts와 packages/ui/src/client.ts로 진입점을 나누는 방식을 택했다.TURBO_TOKEN과 TURBO_TEAM 환경변수를 GitHub Secrets에 등록해야 한다. 이 설정 없이는 CI 빌드마다 전체 캐시가 초기화되어 캐시 효과가 없었다. Self-hosted 원격 캐시 대안으로는 turborepo-remote-cache 오픈소스가 있다..nvmrc 파일을 추가하고 CI에서도 동일 버전을 강제했다. pnpm 버전 통일에는 package.json의 engines 필드와 packageManager 필드를 함께 사용했다.pnpm-workspace.yaml + package.json engines 설정# pnpm-workspace.yaml packages: - 'apps/*' - 'packages/*' # 루트 package.json (일부) { "engines": { "node": ">=20.0.0", "pnpm": ">=9.0.0" }, "packageManager": "pnpm@9.1.0" }
전환 완료 후 6개월이 지난 시점에서 이 팀이 측정한 수치들이다. Turborepo 원격 캐시 히트율이 안정적으로 유지되는 시점(전환 후 약 4주)을 기준으로 비교했다고 한다.
이 팀의 테크리드는 6개월이 지난 시점에서 회고 문서를 작성했다. 핵심 내용 세 가지를 정리하면 다음과 같다.
이 팀의 전환은 Turborepo가 만능 해결책이어서 성공한 게 아니었다. 패키지 경계 설계, 원격 캐시 설정, 팀 환경 표준화라는 세 가지 기반 작업이 선행됐기 때문이었다. Turborepo는 그 기반 위에서 빌드 시간과 배포 사이클을 줄여준 도구였다.
참고 자료: Turborepo 공식 문서, pnpm Workspaces 가이드