Monorepo 도입기: Turborepo 사용 경험

2025-12-19Architecture

서비스 규모가 커지다 보면 어드민(Admin), 사용자 웹(Web), 앱 내 웹뷰(WebView), 그리고 이들이 공통으로 쓰는 디자인 시스템(UI Kit)과 유틸리티 라이브러리(Common Utils)가 생겨납니다. 이를 각각 별도의 Git 저장소(Multirepo)로 관리하다 보면 버전 파편화, 코드 중복, 배포의 번거로움에 시달리게 됩니다.

이런 문제를 해결하기 위해 여러 프로젝트를 하나의 저장소에서 관리하는 Monorepo가 대세가 되었습니다. Lerna, Nx 등 다양한 도구가 있지만, 최근 가장 주목받는 Turborepo의 도입 경험을 공유합니다.

1. Turborepo란?

Vercel이 인수한 고성능 모노레포 빌드 시스템입니다. 핵심 가치는 **"한 번 계산한 건 다시 계산하지 않는다"**입니다.

원격 캐싱(Remote Caching): 내 컴퓨터에서 빌드한 결과를 클라우드에 저장합니다. 동료 개발자는 소스 코드를 받아서 빌드할 필요 없이 캐시만 다운로드하면 됩니다. CI 속도가 비약적으로 빨라집니다.
파이프라인 최적화: 의존성 그래프를 분석하여 병렬로 실행 가능한 작업들을 기가 막히게 스케줄링합니다.

2. 도입 과정

2.1 패키지 매니저 선택 (pnpm)

npm이나 yarn 대신 pnpm을 선택했습니다. node_modules를 심볼릭 링크로 관리하여 디스크 용량을 절약하고 설치 속도가 매우 빠릅니다. 모노레포 워크스페이스(Workspace) 기능과 궁합이 아주 좋습니다.

2.2 폴더 구조

apps/
  web/       (Next.js)
  docs/      (Storybook)
packages/
  ui/        (Shared Components)
  config/    (Shared Eslint, TSConfig)
  utils/     (Shared Logic)

apps와 packages를 분리하여 의존성 방향을 명확히 했습니다.

3. 겪었던 문제점

설정의 복잡함: ESLint, Prettier, TypeScript 설정 파일을 중앙에서 관리하고 각 패키지가 이를 상속(extends)받게 하는 구조를 잡는 데 꽤 시간이 걸렸습니다.
배포 파이프라인: Vercel을 쓰면 알아서 해주지만, AWS나 Docker 환경에 배포할 때는 turbo prune 명령어를 사용하여 해당 앱에 필요한 파일만 쏙 골라내는(Isolate) 과정이 필요했습니다.

결론적으로 모노레포는 "팀의 생산성"을 위한 기술입니다. 코드 공유가 쉬워지고, 전체 프로젝트의 변경 사항을 한눈에 파악할 수 있는 강력한 무기입니다.