2nd/10_Wiki/Topics/Coding/DevOps_Monorepo_Patterns.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
devops-monorepo-patterns	Monorepo — Turborepo / Nx / pnpm workspaces	Coding	draft	B	conceptual	2026-05-09	2026-05-09	devops monorepo turborepo pnpm vibe-coding	language applicable_to Node.js / pnpm / Turborepo Web Backend		workspace packages pnpm turborepo nx

Monorepo

한 repo 에 여러 패키지. 공유 코드 + 원자적 변경 + 통합 CI 의 장점, 빌드 캐시 / 부분 build 가 핵심. pnpm workspaces + Turborepo / Nx 가 2026 스택.

📖 핵심 개념

• Workspace: package.json 의 workspaces 또는 pnpm-workspace.yaml.
• Task graph: turbo.json 또는 nx.json — 패키지 간 의존성 + 캐시.
• 변경 감지: --filter ...[HEAD~1] 으로 영향 받는 패키지만.

💻 코드 패턴

pnpm workspaces

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

.
├── apps/
│   ├── web/        # Next.js
│   └── mobile/     # React Native
├── packages/
│   ├── ui/         # 공유 UI 컴포넌트
│   ├── shared/     # 공유 로직
│   └── eslint-config/
└── pnpm-workspace.yaml

패키지 간 의존

// apps/web/package.json
{
  "dependencies": {
    "@scope/ui": "workspace:*",
    "@scope/shared": "workspace:*"
  }
}

Turborepo task graph

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],            // 의존 패키지 build 먼저
      "outputs": ["dist/**", ".next/**"],
      "inputs": ["src/**", "package.json"]
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"]
    },
    "lint": { "dependsOn": [] },
    "dev": { "cache": false, "persistent": true }
  }
}

turbo run build           # 모든 패키지 build (의존 순서 + 캐시)
turbo run test --filter=@scope/ui
turbo run build --filter=...[HEAD~1]   # 변경 영향만

CI — 변경 영향만 build

- name: Build affected
  run: pnpm turbo run build --filter=...[origin/main]

Remote cache — 팀 공유

turbo login
turbo link
# 이후 모든 빌드가 Vercel / 자체 cache 와 공유

Versioning — Changesets

pnpm changeset           # 변경 영향 + 노트 작성
pnpm changeset version   # version bump
pnpm changeset publish   # npm publish (필요시)

🤔 의사결정 기준

상황	도구
Node.js 다수 패키지	pnpm + Turborepo
다언어 (Go + TS + Python)	Bazel / Nx
작은 팀, 2-3 패키지	pnpm workspaces 만, Turbo 없이
Mobile + Web 공유 코드	Yarn Berry + workspace 또는 pnpm
OSS 라이브러리 + example	Turborepo example template
큰 팀 + 다양 언어	Nx (graph 시각화 강함)

❌ 안티패턴

• npm install 모든 곳 별도: deps 중복. workspace 사용.
• 버전 hoisting 가정: pnpm 은 strict — peer dep 명시 필수.
• package 간 circular dep: 빌드 끝없이 회전. Turbo 가 fail.
• task output 정의 안 함: 캐시 안 됨. outputs 필드.
• dev 와 build 캐시 같이: dev 는 "cache": false.
• monorepo + git submodule 혼용: 복잡. 한 모델.
• 패키지 이름 namespace 없음: 충돌. @scope/* 권장.
• CI 가 항상 모든 패키지 build: 시간 폭증. --filter 로 affected 만.

🤖 LLM 활용 힌트

• pnpm workspaces + Turborepo + Changesets 가 표준 스택.
• task 마다 inputs / outputs 정확히 → 캐시 효력.

🔗 관련 문서

• DevOps_Build_Performance
• Android_Modularization