2nd/10_Wiki/Topics/Architecture/Monorepo.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-monorepo	Monorepo	10_Wiki/Topics	verified	self	Mono Repo Single Repository Polyrepo Alternative	none	A	0.9	applied	monorepo build-system turborepo nx bazel		2026-05-10	pending	language framework typescript turborepo-nx

Monorepo

매 한 줄

"매 single repo, 매 multiple project, 매 shared code, 매 atomic commit". Google/Meta scale 의 Bazel/Buck 의 origin. 2026 mainstream 의 Turborepo 2.x / Nx 21 / pnpm workspaces — 매 small team 도 의 monorepo 의 가능.

매 핵심

매 benefit

• Atomic refactor: 매 lib API change + 매 caller update 의 1 PR.
• Shared dependency: 매 single version policy. No "diamond dep" hell.
• Code reuse: 매 internal lib import 의 trivial.
• Unified tooling: 매 lint, test, CI 의 1 config.

매 cost

• Build complexity: 매 selective rebuild 의 essential.
• Repo size: 매 git clone 의 slow. Sparse checkout / partial clone.
• CI scaling: 매 every PR 의 entire repo 의 test = N/A. Affected-only.
• Access control: 매 fine-grained permission 의 hard.

매 응용

1. Frontend + backend + shared types: pnpm workspaces.
2. 50+ packages, JS/TS heavy: Turborepo or Nx.
3. Polyglot (Go + Rust + TS), large: Bazel/Pants.

💻 패턴

pnpm workspace

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

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

Turborepo pipeline

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {},
    "dev": { "cache": false, "persistent": true }
  }
}

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

Nx affected

nx affected -t build test lint --base=origin/main
nx graph --affected

Remote cache (Turborepo)

npx turbo login
npx turbo link
# pushes/pulls cache from Vercel

Shared TS config

// packages/tsconfig/base.json
{
  "compilerOptions": {
    "target": "es2022",
    "module": "esnext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true
  }
}

// apps/web/tsconfig.json
{ "extends": "@acme/tsconfig/base.json" }

Dependency boundary (ESLint)

{
  "rules": {
    "@nx/enforce-module-boundaries": ["error", {
      "depConstraints": [
        { "sourceTag": "scope:web", "onlyDependOnLibsWithTags": ["scope:web", "scope:shared"] },
        { "sourceTag": "scope:api", "onlyDependOnLibsWithTags": ["scope:api", "scope:shared"] }
      ]
    }]
  }
}

Changesets (versioning)

pnpm changeset           # author intent
pnpm changeset version   # bump versions
pnpm changeset publish   # publish to npm

Sparse checkout

git clone --filter=blob:none --sparse https://github.com/acme/monorepo
cd monorepo
git sparse-checkout set apps/web packages/ui

CI: changed-files matrix

# .github/workflows/ci.yml
jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      packages: ${{ steps.filter.outputs.changes }}
    steps:
      - uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
            web: apps/web/**
            api: apps/api/**
            ui: packages/ui/**
  build:
    needs: changes
    strategy:
      matrix: { pkg: ${{ fromJSON(needs.changes.outputs.packages) }} }
    steps:
      - run: pnpm --filter @acme/${{ matrix.pkg }} build

매 결정 기준

상황	Approach
2-5 packages, JS/TS	pnpm workspaces only
5-50 packages, JS/TS	Turborepo + remote cache
50+ packages, plugin ecosystem	Nx
Polyglot, Google-scale	Bazel / Pants / Buck2

기본값: pnpm + Turborepo (TS-heavy projects).

🔗 Graph

• 부모: Build-Systems · Source-Control
• 변형: Polyrepo · Multi-Repo
• 응용: Modular-Programming · Workspace-Management
• Adjacent: Bazel · Nx · Turborepo · pnpm

🤖 LLM 활용

언제: 매 task pipeline 의 setup, dependency graph 의 visualize, affected-only command 의 generate, package.json 의 boilerplate. 언제 X: 매 organizational decision (mono vs poly) — Conway's law + team topology judgment.

❌ 안티패턴

• No build cache: 매 PR 의 매 full rebuild = CI cost explosion.
• Inconsistent tooling: 매 package 의 own ESLint config = chaos.
• Cyclic package deps: A → B → A. nx graph / turbo 의 detect.
• Ignoring affected: 매 always full test = 매 monorepo 의 advantage 의 lose.

🧪 검증 / 중복

• Verified (Turborepo docs, Nx docs, "Software Engineering at Google" Ch 16, Vercel monorepo handbook 2025).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — canonical monorepo with Turborepo/Nx/pnpm patterns