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

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-turborepo	Turborepo	10_Wiki/Topics	verified	self	turbo Turbo Build	none	A	0.9	applied	monorepo build-tool vercel turborepo		2026-05-10	pending	language framework typescript 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 기본

{
  "$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

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

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

Package dependency

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

Run tasks

# 매 모든 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)

turbo login
turbo link
# 매 이후 매 build 의 cache 가 team 간 share

Self-hosted remote cache

// turbo.json
{
  "remoteCache": {
    "signature": true
  }
}

# Env vars
TURBO_API=https://my-cache.example.com
TURBO_TOKEN=xxx
TURBO_TEAM=team_xxx

Generators

turbo gen
# 매 interactive — new package / new component

// 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

# .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