Turborepo 완벽 가이드 | Monorepo·빌드 캐싱·병렬 실행·pnpm·실전 활용
이 글의 핵심
Turborepo로 고성능 Monorepo를 구축하는 완벽 가이드입니다. 빌드 캐싱, 병렬 실행, pnpm Workspace 통합까지 실전 예제로 정리했습니다.
실무 경험 공유: Lerna에서 Turborepo로 전환하면서, 빌드 시간이 10분에서 2분으로 단축되고 CI/CD가 5배 빨라진 경험을 공유합니다.
들어가며: “Monorepo 빌드가 느려요”
실무 문제 시나리오
시나리오 1: 빌드가 너무 느려요
순차 빌드는 느립니다. Turborepo는 병렬 실행합니다.
시나리오 2: 캐싱이 없어요
매번 전체 빌드합니다. Turborepo는 스마트 캐싱을 제공합니다.
시나리오 3: 의존성 관리가 어려워요
수동 관리가 필요합니다. Turborepo는 자동으로 처리합니다.
1. Turborepo란?
핵심 특징
Turborepo는 Vercel이 만든 고성능 Monorepo 빌드 시스템입니다.
주요 장점:
- 빠른 빌드: 병렬 실행
- 스마트 캐싱: 변경된 것만 빌드
- Remote Cache: 팀 간 캐시 공유
- 간단한 설정: 최소한의 설정
- pnpm/yarn/npm: 모두 지원
2. 프로젝트 설정
설치
npx create-turbo@latest프로젝트 구조
my-turborepo/
├── apps/
│ ├── web/
│ │ ├── package.json
│ │ └── next.config.js
│ └── docs/
│ ├── package.json
│ └── next.config.js
├── packages/
│ ├── ui/
│ │ ├── package.json
│ │ └── src/
│ ├── config/
│ │ └── package.json
│ └── tsconfig/
│ └── package.json
├── turbo.json
├── pnpm-workspace.yaml
└── package.json3. turbo.json 설정
{
"$schema": "https://turbo.build/schema.json",
"globalDependencies": [**/.env.*local],
"pipeline": {
"build": {
"dependsOn": [^build],
"outputs": [".next/**", "dist/**"],
"env": [NEXT_PUBLIC_API_URL]
},
"dev": {
"cache": false,
"persistent": true
},
"test": {
"dependsOn": [build],
"outputs": [coverage/**]
},
"lint": {
"outputs": []
},
"type-check": {
"dependsOn": [^build],
"outputs": []
}
}
}4. 공유 패키지
UI 패키지
// packages/ui/src/Button.tsx
export function Button({ children, onClick }: ButtonProps) {
return (
<button onClick={onClick} className="btn">
{children}
</button>
);
}// packages/ui/package.json
{
"name": "ui",
"main": "./src/index.tsx",
"types": "./src/index.tsx",
"scripts": {
"lint": "eslint .",
"type-check": "tsc --noEmit"
}
}Config 패키지
// packages/config/eslint-preset.js
module.exports = {
extends: ['next', 'turbo', 'prettier'],
rules: {
'@next/next/no-html-link-for-pages': 'off',
},
};5. 실행 명령어
개발
# 모든 앱 실행
pnpm dev
# 특정 앱만 실행
pnpm --filter web dev빌드
# 모든 앱 빌드
pnpm build
# 특정 앱과 의존성 빌드
pnpm --filter web... build테스트
# 모든 패키지 테스트
pnpm test
# 변경된 패키지만 테스트
pnpm test --filter ...[HEAD^]6. Remote Cache
Vercel Remote Cache
# 로그인
npx turbo login
# 링크
npx turbo link사용
# 자동으로 remote cache 사용
pnpm build효과:
- 팀 간 캐시 공유
- CI/CD 속도 향상
- 로컬 빌드 속도 향상
7. CI/CD 최적화
GitHub Actions
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: pnpm/action-setup@v2
with:
version: 8
- uses: actions/setup-node@v3
with:
node-version: 20
cache: 'pnpm'
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Build
run: pnpm turbo build
env:
TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
- name: Test
run: pnpm turbo test8. 실전 팁
1. 의존성 그래프 확인
pnpm turbo run build --graph2. 캐시 무효화
pnpm turbo run build --force3. 로그 상세화
pnpm turbo run build --verbose4. 병렬 실행 제한
{
"pipeline": {
"build": {
"dependsOn": [^build],
"outputs": [.next/**]
}
},
"globalEnv": [NODE_ENV],
"globalPassThroughEnv": [CI]
}정리 및 체크리스트
핵심 요약
- Turborepo: 고성능 Monorepo 빌드
- 병렬 실행: 빠른 빌드
- 스마트 캐싱: 변경된 것만
- Remote Cache: 팀 간 공유
- pnpm: 완벽한 통합
- 간단한 설정: 최소한의 설정
구현 체크리스트
- Turborepo 설치
- 프로젝트 구조 설정
- turbo.json 작성
- 공유 패키지 생성
- Remote Cache 설정
- CI/CD 통합
- 성능 최적화
같이 보면 좋은 글
- pnpm 완벽 가이드
- Docker Compose 완벽 가이드
- Monorepo 아키텍처 가이드
이 글에서 다루는 키워드
Turborepo, Monorepo, Build, Cache, pnpm, Performance, DevOps
자주 묻는 질문 (FAQ)
Q. Lerna와 비교하면 어떤가요?
A. Turborepo가 훨씬 빠르고 간단합니다. Lerna는 더 많은 기능을 제공하지만 복잡합니다.
Q. Nx와 비교하면 어떤가요?
A. Turborepo가 더 간단합니다. Nx는 더 많은 기능과 플러그인을 제공합니다.
Q. 무료로 사용할 수 있나요?
A. 네, 오픈소스입니다. Remote Cache는 Vercel 계정이 필요하지만 무료 플랜이 있습니다.
Q. 프로덕션에서 사용해도 되나요?
A. 네, Vercel, Netflix 등 많은 기업에서 사용합니다.