🚀

Turborepo로 모노레포 구축하기

2025.10.11

Turborepo란?

Turborepo는 JavaScript와 TypeScript 프로젝트를 위한 고성능 빌드 시스템이다.
Vercel에서 개발하고 있으며, 모노레포(Monorepo) 환경에서 빌드 속도를 극적으로 향상시켜준다.

모노레포(Monorepo)가 뭔데?

모노레포는 여러 프로젝트를 하나의 저장소에서 관리하는 방식이다.
예를 들어 프론트엔드, 백엔드, 공통 라이브러리를 하나의 레포지토리에서 관리할 수 있다.

장점

코드 공유가 쉽다
일관된 개발 환경 유지
의존성 관리가 편리하다
원자적 커밋 가능 (여러 패키지 변경을 한 커밋으로)

단점

저장소 크기가 커진다
빌드 시간이 오래 걸릴 수 있다 → Turborepo가 해결!

Turborepo의 핵심 기능

1. 캐싱 (Caching)

Turborepo의 가장 강력한 기능이다.
한 번 빌드한 결과를 캐싱해서, 코드가 변경되지 않으면 다시 빌드하지 않는다.

# 첫 번째 빌드
$ turbo build
# Tasks: 3 successful, 3 total
# Time: 15.2s

# 두 번째 빌드 (캐시 히트)
$ turbo build
# Tasks: 3 successful, 3 total
# Time: 0.5s >>> FULL TURBO

2. 병렬 실행 (Parallel Execution)

의존 관계가 없는 태스크들은 동시에 실행한다.
CPU 코어를 최대한 활용해서 빌드 시간을 단축시킨다.

3. Remote Caching

팀원들과 캐시를 공유할 수 있다.
A 개발자가 빌드한 결과를 B 개발자가 그대로 사용할 수 있어서, 팀 전체의 빌드 시간이 줄어든다.

시작하기

새 프로젝트 생성

npx create-turbo@latest my-turborepo
cd my-turborepo

기존 프로젝트에 추가

npm install turbo --save-dev

프로젝트 구조

Turborepo의 기본 구조는 다음과 같다.

my-turborepo/
├── apps/
│   ├── web/          # Next.js 앱
│   └── docs/         # 문서 사이트
├── packages/
│   ├── ui/           # 공유 UI 컴포넌트
│   ├── config/       # 공유 설정 (ESLint, TypeScript 등)
│   └── utils/        # 공유 유틸리티
├── turbo.json        # Turborepo 설정
└── package.json      # 루트 package.json

turbo.json 설정

프로젝트 루트에 turbo.json 파일을 생성한다.

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {},
    "test": {
      "dependsOn": ["build"]
    }
  }
}

주요 옵션 설명

옵션	설명
`dependsOn`	이 태스크 실행 전에 먼저 실행해야 할 태스크
`^build`	의존하는 패키지들의 build를 먼저 실행
`outputs`	캐싱할 출력 파일/폴더
`cache`	캐싱 여부 (dev는 보통 false)
`persistent`	계속 실행되는 태스크 여부

패키지 간 의존성 설정

packages/ui/package.json

{
  "name": "@repo/ui",
  "version": "0.0.0",
  "exports": {
    ".": "./src/index.ts"
  }
}

apps/web/package.json

{
  "name": "web",
  "dependencies": {
    "@repo/ui": "*"
  }
}

이제 web 앱에서 ui 패키지를 사용할 수 있다.

import { Button } from '@repo/ui';

export default function Home() {
  return <Button>Click me</Button>;
}

자주 사용하는 명령어

# 모든 패키지 빌드
turbo build

# 특정 패키지만 빌드
turbo build --filter=web

# 특정 패키지와 의존성 모두 빌드
turbo build --filter=web...

# 개발 서버 실행
turbo dev

# 캐시 삭제
turbo clean

# 변경된 패키지만 빌드
turbo build --filter=[origin/main]

Remote Caching 설정

Vercel과 연동하면 팀원들과 캐시를 공유할 수 있다.

# Vercel 로그인
npx turbo login

# Remote Caching 연결
npx turbo link

이후 빌드하면 캐시가 클라우드에 저장되고, 다른 팀원이나 CI에서 재사용할 수 있다.

실제 사용 예시

공통 컴포넌트 라이브러리 만들기

packages/ui/src/Button.tsx

interface ButtonProps {
  children: React.ReactNode;
  variant?: 'primary' | 'secondary';
  onClick?: () => void;
}

export const Button = ({
  children,
  variant = 'primary',
  onClick
}: ButtonProps) => {
  return (
    <button
      className={`btn btn-${variant}`}
      onClick={onClick}
    >
      {children}
    </button>
  );
};