Turborepo 완벽 가이드 | 모노레포·빌드 캐싱·파이프라인·Remote Cache

· 18분 읽기 · 수정 중급
Turborepo 완벽 가이드 | 모노레포·빌드 캐싱·파이프라인·Remote Cache

이 글의 핵심

Turborepo로 고성능 모노레포를 구축하는 완벽 가이드입니다. 설치부터 워크스페이스, 빌드 캐싱, 파이프라인, Remote Cache, Vercel 배포까지 실전 예제로 정리했습니다.

실무 경험 공유: 10개 이상의 패키지를 가진 모노레포에 Turborepo를 도입하면서, 빌드 시간을 20분에서 2분으로 단축하고 CI/CD 비용을 70% 절감한 경험을 공유합니다.

들어가며: “모노레포 빌드가 너무 느려요”

실무 문제 시나리오

시나리오 1: 전체 빌드가 20분 걸려요
모든 패키지를 매번 빌드합니다. Turborepo는 변경된 것만 빌드합니다.

시나리오 2: 의존성 순서가 복잡해요
패키지 간 의존성 순서를 수동 관리합니다. Turborepo는 자동으로 처리합니다.

시나리오 3: CI에서 매번 처음부터 빌드해요
캐시가 없어 CI가 느립니다. Turborepo Remote Cache로 해결합니다.

1. Turborepo란?

핵심 특징

Turborepo는 Vercel이 만든 고성능 빌드 시스템입니다.

주요 장점:

  • 빠른 빌드: 증분 빌드 + 병렬 실행
  • 스마트 캐싱: 변경되지 않은 작업 스킵
  • Remote Cache: 팀 전체가 캐시 공유
  • 파이프라인: 작업 의존성 자동 관리
  • 간단한 설정: 최소한의 설정으로 시작

2. 설치 및 초기 설정

새 프로젝트 생성

npx create-turbo@latest

기존 프로젝트에 추가

npm install turbo --save-dev

디렉터리 구조

my-turborepo/
├── apps/
│   ├── web/          # Next.js 앱
│   └── docs/         # 문서 사이트
├── packages/
│   ├── ui/           # 공유 UI 컴포넌트
│   ├── utils/        # 유틸리티
│   └── tsconfig/     # 공유 TypeScript 설정
├── turbo.json
├── package.json
└── pnpm-workspace.yaml

3. turbo.json 설정

기본 설정

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

파이프라인 설명

  • ^build: 의존하는 패키지의 build가 먼저 실행
  • outputs: 캐시할 출력 파일
  • cache: false: 캐싱 비활성화 (dev 서버)
  • persistent: 백그라운드에서 계속 실행

4. 기본 명령어

빌드

# 모든 패키지 빌드
turbo run build

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

# 병렬 실행 제한
turbo run build --concurrency=4

개발

# 모든 앱 개발 모드
turbo run dev

# 특정 앱만
turbo run dev --filter=web

테스트

# 모든 테스트 실행
turbo run test

# 변경된 패키지만 테스트
turbo run test --filter=[HEAD^1]

5. 실전 예제: 풀스택 모노레포

프로젝트 구조

mkdir my-turborepo
cd my-turborepo
pnpm init

pnpm-workspace.yaml

packages:
  - 'apps/*'
  - 'packages/*'

turbo.json

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

UI 패키지

// packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "0.0.0",
  "main": "./src/index.tsx",
  "types": "./src/index.tsx",
  "scripts": {
    "lint": "eslint .",
    "test": "jest"
  },
  "devDependencies": {
    "@types/react": "^18.0.0",
    "react": "^18.0.0",
    "typescript": "^5.0.0"
  }
}
// packages/ui/src/index.tsx
export { Button } from './button';
export { Input } from './input';
// packages/ui/src/button.tsx
export function Button({ children, ...props }: React.ButtonHTMLAttributes<HTMLButtonElement>) {
  return (
    <button
      className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
      {...props}
    >
      {children}
    </button>
  );
}

Web 앱

// apps/web/package.json
{
  "name": "web",
  "version": "0.0.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "@repo/ui": "workspace:*",
    "next": "^14.0.0",
    "react": "^18.0.0"
  }
}
// apps/web/app/page.tsx
import { Button } from '@repo/ui';

export default function Home() {
  return (
    <main>
      <h1>Welcome to Turborepo</h1>
      <Button>Click me</Button>
    </main>
  );
}

6. 캐싱

로컬 캐시

# 첫 번째 빌드
turbo run build
# ✓ Building...

# 두 번째 빌드 (캐시 사용)
turbo run build
# >>> FULL TURBO (캐시에서 복원)

캐시 확인

# 캐시 상태 확인
turbo run build --dry-run

# 캐시 무시
turbo run build --force

캐시 정리

# 로컬 캐시 삭제
rm -rf .turbo

7. Remote Cache (Vercel)

설정

# Vercel 로그인
npx turbo login

# Remote Cache 연결
npx turbo link

사용

# Remote Cache 사용
turbo run build

# 팀원이 빌드 시 자동으로 캐시 재사용

장점

  • 팀 전체 캐시 공유: 한 번 빌드하면 모두 사용
  • CI 속도 향상: CI에서도 캐시 재사용
  • 비용 절감: 불필요한 빌드 제거

8. 필터링

특정 패키지

# web 앱만 빌드
turbo run build --filter=web

# ui 패키지와 의존하는 모든 것
turbo run build --filter=...@repo/ui

# ui 패키지에 의존하는 모든 것
turbo run build --filter=@repo/ui...

Git 기반 필터링

# 변경된 패키지만 빌드
turbo run build --filter=[HEAD^1]

# main 브랜치와 비교
turbo run build --filter=[origin/main]

9. CI/CD 통합

GitHub Actions

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
      
      - run: pnpm install
      
      # Turborepo Remote Cache
      - name: Build
        run: pnpm turbo run build
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
      
      - name: Test
        run: pnpm turbo run test
      
      - name: Lint
        run: pnpm turbo run lint

10. 성능 최적화

병렬 실행

{
  "pipeline": {
    "build": {
      "dependsOn": [^build],
      "outputs": [dist/**]
    },
    "test": {
      "dependsOn": [build],
      "outputs": [coverage/**]
    }
  }
}

출력 최적화

{
  "pipeline": {
    "build": {
      "outputs": [
        ".next/**",
        "!.next/cache/**",  // 캐시 제외
        "dist/**"
      ]
    }
  }
}

11. 실전 팁

환경 변수

{
  "globalDependencies": [
    "**/.env.*local",
    ".env"
  ],
  "pipeline": {
    "build": {
      "env": ["NODE_ENV", "API_URL"]
    }
  }
}

프로파일링

# 빌드 프로파일 생성
turbo run build --profile=profile.json

# 프로파일 확인
open https://turbo.build/viewer

정리 및 체크리스트

핵심 요약

  • Turborepo: 고성능 모노레포 빌드 시스템
  • 스마트 캐싱: 변경되지 않은 작업 스킵
  • Remote Cache: 팀 전체 캐시 공유
  • 파이프라인: 작업 의존성 자동 관리
  • 빠른 빌드: 증분 빌드 + 병렬 실행

구현 체크리스트

  • Turborepo 설치
  • turbo.json 설정
  • 파이프라인 정의
  • Remote Cache 연결
  • CI/CD 통합
  • 성능 모니터링

같이 보면 좋은 글

  • pnpm 완벽 가이드
  • GitHub Actions CI/CD 완벽 가이드
  • Next.js 15 완벽 가이드

이 글에서 다루는 키워드

Turborepo, Monorepo, Build Tool, Caching, pnpm, Workspace, DevOps

자주 묻는 질문 (FAQ)

Q. Turborepo vs Nx, 어떤 게 나은가요?

A. Turborepo는 더 간단하고 빠릅니다. Nx는 더 많은 기능을 제공하지만 복잡합니다. 대부분의 경우 Turborepo로 충분합니다.

Q. Remote Cache 비용은 얼마인가요?

A. Vercel의 Hobby 플랜은 무료입니다. Pro 플랜은 월 $20부터 시작합니다.

Q. pnpm 없이 사용할 수 있나요?

A. 네, npm, yarn도 지원합니다. 하지만 pnpm이 가장 빠릅니다.

Q. 기존 모노레포에 추가하기 어렵나요?

A. 매우 쉽습니다. turbo.json만 추가하면 됩니다. 점진적 도입이 가능합니다.

... 996 lines not shown ... Token usage: 63706/1000000; 936294 remaining Start-Sleep -Seconds 3