[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -0,0 +1,131 @@
+---
+id: devops-monorepo-patterns
+title: Monorepo — Turborepo / Nx / pnpm workspaces
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [devops, monorepo, turborepo, pnpm, vibe-coding]
+tech_stack: { language: "Node.js / pnpm / Turborepo", applicable_to: ["Web", "Backend"] }
+applied_in: []
+aliases: [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
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - "apps/*"
+  - "packages/*"
+```
+
+```
+.
+├── apps/
+│   ├── web/        # Next.js
+│   └── mobile/     # React Native
+├── packages/
+│   ├── ui/         # 공유 UI 컴포넌트
+│   ├── shared/     # 공유 로직
+│   └── eslint-config/
+└── pnpm-workspace.yaml
+```
+
+### 패키지 간 의존
+```json
+// apps/web/package.json
+{
+  "dependencies": {
+    "@scope/ui": "workspace:*",
+    "@scope/shared": "workspace:*"
+  }
+}
+```
+
+### Turborepo task graph
+```json
+// 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 }
+  }
+}
+```
+
+```bash
+turbo run build           # 모든 패키지 build (의존 순서 + 캐시)
+turbo run test --filter=@scope/ui
+turbo run build --filter=...[HEAD~1]   # 변경 영향만
+```
+
+### CI — 변경 영향만 build
+```yaml
+- name: Build affected
+  run: pnpm turbo run build --filter=...[origin/main]
+```
+
+### Remote cache — 팀 공유
+```bash
+turbo login
+turbo link
+# 이후 모든 빌드가 Vercel / 자체 cache 와 공유
+```
+
+### Versioning — Changesets
+```bash
+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]]