2nd/10_Wiki/Topics/Architecture/Turborepo.md

---
id: wiki-2026-0508-turborepo
title: Turborepo
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [turbo, Turbo Build]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [monorepo, build-tool, vercel, turborepo]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: turborepo-2
---

# Turborepo

## 매 한 줄
> **"매 monorepo 의 incremental task runner — 매 task graph + cache 가 매 핵심"**. 2026 현재 Turborepo 2.x — Rust core, remote cache (Vercel), task pipelining, package-based monorepo. 매 Nx 의 lighter alternative.

## 매 핵심

### 매 build blocks
- **`turbo.json`**: 매 task pipeline 정의.
- **`pnpm` workspaces** (또는 npm/yarn): 매 package graph.
- **Local cache**: `.turbo/` — content-addressed.
- **Remote cache**: Vercel / 자체 S3 — team 간 share.

### 매 task graph
- 매 task 는 `^build` (dependencies first) 또는 `build` (current package).
- 매 input/output 명시 → cache hash.
- 매 변경 없으면 **FULL TURBO** (cache hit) — 0ms.

### 매 응용
1. Next.js + multiple apps 의 monorepo.
2. Shared `ui` / `config` / `types` packages.
3. CI 의 affected-only build.

## 💻 패턴

### `turbo.json` 기본
```json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"]
    },
    "lint": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", ".eslintrc.*"]
    },
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "test/**"],
      "outputs": ["coverage/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}
```

### Workspace structure
```text
my-monorepo/
├── apps/
│   ├── web/          # Next.js
│   └── docs/         # Next.js
├── packages/
│   ├── ui/           # shared components
│   ├── config-eslint/
│   └── tsconfig/
├── package.json
├── pnpm-workspace.yaml
└── turbo.json
```

```yaml
# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"
```

### Package dependency
```json
// apps/web/package.json
{
  "name": "web",
  "dependencies": {
    "@repo/ui": "workspace:*",
    "next": "^15.0.0"
  }
}
```

### Run tasks
```bash
# 매 모든 packages 의 build
turbo build

# 매 specific app + dependencies
turbo build --filter=web

# 매 affected by changes since main
turbo build --filter=...[origin/main]

# Watch mode (dev)
turbo dev
```

### Remote cache (Vercel)
```bash
turbo login
turbo link
# 매 이후 매 build 의 cache 가 team 간 share
```

### Self-hosted remote cache
```json
// turbo.json
{
  "remoteCache": {
    "signature": true
  }
}
```
```bash
# Env vars
TURBO_API=https://my-cache.example.com
TURBO_TOKEN=xxx
TURBO_TEAM=team_xxx
```

### Generators
```bash
turbo gen
# 매 interactive — new package / new component
```

```typescript
// turbo/generators/config.ts
import type { PlopTypes } from "@turbo/gen";

export default function generator(plop: PlopTypes.NodePlopAPI) {
  plop.setGenerator("package", {
    description: "New package",
    prompts: [{ type: "input", name: "name", message: "Package name?" }],
    actions: [
      {
        type: "add",
        path: "packages/{{name}}/package.json",
        templateFile: "templates/package.json.hbs",
      },
    ],
  });
}
```

### CI optimization
```yaml
# .github/workflows/ci.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 2  # 매 affected detection
- uses: pnpm/action-setup@v3
- run: pnpm install
- run: pnpm turbo build lint test --filter=...[HEAD^]
  env:
    TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
    TURBO_TEAM: ${{ vars.TURBO_TEAM }}
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| 매 JS/TS monorepo + Vercel | Turborepo |
| 매 polyglot monorepo | Nx (또는 Bazel) |
| 매 small repo (<5 packages) | pnpm workspaces only |
| 매 enterprise scale (100+) | Nx 또는 Bazel |

**기본값**: 매 JS/TS team 은 Turborepo 2 + pnpm.

## 🔗 Graph
- 부모: [[Monorepo]]
- 변형: [[Nx]] · [[Bazel]]
- 응용: [[Nextjs]] · [[pnpm]]

## 🤖 LLM 활용
**언제**: 매 turbo.json scaffold, 매 task pipeline debug, 매 cache miss diagnosis.
**언제 X**: 매 enterprise polyglot — Nx / Bazel 의 더 적합.

## ❌ 안티패턴
- **Missing inputs/outputs**: 매 cache 가 stale.
- **`cache: false` everywhere**: 매 turbo 의 가치 상실.
- **Circular deps**: 매 task graph 가 broken.
- **Large `node_modules` in cache outputs**: 매 cache size 폭발.

## 🧪 검증 / 중복
- Verified (Turborepo 2.x docs, Vercel, 2026).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — Turborepo 2 with task graph, remote cache, generators |