모노레포 전략 가이드 2025: Nx vs Turborepo vs Lerna — 대규모 코드베이스 관리의 모든 것

프로젝트 시작?
├── 소규모 (패키지 10개 미만)
│   ├── 빠른 시작 원함 → Turborepo
│   └── 코드 생성 필요 → Nx
├── 중규모 (패키지 10-50개)
│   ├── Vercel/Next.js 생태계 → Turborepo
│   ├── 풍부한 플러그인 필요 → Nx
│   └── 기존 Lerna 사용 중 → Lerna v7
└── 대규모 (패키지 50개 이상)
    ├── 분산 실행 필요 → Nx
    └── Microsoft 스타일 → Rush

my-monorepo/
├── pnpm-workspace.yaml
├── package.json
├── .npmrc
├── apps/
│   ├── web/
│   │   └── package.json
│   └── api/
│       └── package.json
├── packages/
│   ├── ui/
│   │   └── package.json
│   ├── utils/
│   │   └── package.json
│   └── config/
│       └── package.json
└── tooling/
    ├── eslint/
    │   └── package.json
    └── typescript/
        └── package.json

packages:
  - "apps/*"
  - "packages/*"
  - "tooling/*"

{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint",
    "test": "turbo run test",
    "clean": "turbo run clean"
  },
  "devDependencies": {
    "turbo": "^2.0.0"
  },
  "packageManager": "pnpm@9.0.0"
}

{
  "name": "@myorg/web",
  "dependencies": {
    "@myorg/ui": "workspace:*",
    "@myorg/utils": "workspace:*"
  }
}

# 호이스팅 설정
shamefully-hoist=false
strict-peer-dependencies=false

# 워크스페이스 설정
link-workspace-packages=true
prefer-workspace-packages=true

# 새 Nx 워크스페이스 생성
npx create-nx-workspace@latest my-monorepo --preset=ts

# 기존 모노레포에 Nx 추가
npx nx@latest init

{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "cache": true
    },
    "test": {
      "inputs": ["default", "^production"],
      "cache": true
    },
    "lint": {
      "inputs": ["default", "{workspaceRoot}/.eslintrc.json"],
      "cache": true
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/*.spec.ts",
      "!{projectRoot}/tsconfig.spec.json"
    ],
    "sharedGlobals": ["{workspaceRoot}/tsconfig.base.json"]
  },
  "nxCloudAccessToken": "your-token-here"
}

# 프로젝트 의존성 그래프 시각화
npx nx graph

# 특정 프로젝트의 의존 관계 확인
npx nx graph --focus=my-app

# 영향받는 프로젝트 확인
npx nx affected:graph

프로젝트 그래프 예시:

    web-app ───▶ ui-lib ───▶ utils
       │            │
       ▼            ▼
    api-app ───▶ shared-types

# 변경된 코드에 영향받는 프로젝트만 빌드
npx nx affected -t build

# 영향받는 프로젝트만 테스트
npx nx affected -t test

# base 브랜치 지정
npx nx affected -t build --base=main --head=HEAD

# React 컴포넌트 생성
npx nx generate @nx/react:component Button --project=ui

# 라이브러리 생성
npx nx generate @nx/js:library shared-utils

# 커스텀 Generator 생성
npx nx generate @nx/plugin:generator my-generator --project=tools

# Nx Cloud 연결
npx nx connect

# 분산 실행 설정 (CI에서)
# .github/workflows/ci.yml

name: CI
on: [push]
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
      - run: pnpm install --frozen-lockfile
      - uses: nrwl/nx-set-shas@v4
      - run: npx nx affected -t lint test build

# 새 Turborepo 프로젝트 생성
npx create-turbo@latest

# 기존 모노레포에 Turborepo 추가
pnpm add -D turbo -w

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "globalEnv": ["NODE_ENV"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "env": ["DATABASE_URL"]
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["$TURBO_DEFAULT$"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "dependsOn": ["^build"],
      "cache": true
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "clean": {
      "cache": false
    }
  }
}

turbo run build 실행 시:

1. 의존성 그래프 분석
   utils (의존 없음) → ui (utils에 의존) → web (ui, utils에 의존)

2. 병렬 실행
   [utils: build] ──완료──▶ [ui: build] ──완료──▶ [web: build]
                            [api: build] ──────────┘
                              (utils에만 의존)

3. 캐싱
   - 입력 파일의 해시 계산
   - 이전 빌드와 해시 동일하면 캐시에서 복원
   - 빌드 시간: 5분 → 0.1초 (캐시 히트)

# 로컬 캐시 위치
ls node_modules/.cache/turbo/

# 캐시 상태 확인
turbo run build --dry-run

# 캐시 무효화
turbo run build --force

# 원격 캐시 활성화
npx turbo login
npx turbo link

# 특정 패키지만 빌드
turbo run build --filter=@myorg/web

# 변경된 패키지만 빌드
turbo run build --filter=...[HEAD^1]

# 특정 패키지와 그 의존성만 빌드
turbo run build --filter=@myorg/web...

# 특정 디렉토리의 패키지만
turbo run build --filter=./apps/*

# Vercel Remote Cache (공식)
npx turbo login
npx turbo link

# 셀프호스팅 (ducktape/turborepo-remote-cache)
# turbo.json에 추가:

{
  "remoteCache": {
    "signature": true
  }
}

TURBO_TOKEN=your-token
TURBO_TEAM=your-team
TURBO_API=https://your-cache-server.com

packages/
├── ui/              # UI 컴포넌트 (Button, Modal, Form)
├── utils/           # 유틸리티 (날짜, 문자열, 검증)
├── types/           # 공유 TypeScript 타입
├── config/          # 공유 설정 (ESLint, TypeScript, Prettier)
├── hooks/           # 공유 React hooks
├── api-client/      # API 클라이언트 (타입 안전 fetch)
└── constants/       # 상수 (에러 코드, 라우트 경로)

{
  "name": "@myorg/ui",
  "private": true,
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": "./src/index.ts",
    "./*": "./src/*.ts"
  }
}

{
  "compilerOptions": {
    "paths": {
      "@myorg/ui": ["../../packages/ui/src"],
      "@myorg/ui/*": ["../../packages/ui/src/*"]
    }
  }
}

{
  "name": "@myorg/utils",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts"
  }
}

# 설치
pnpm add -D @changesets/cli -w

# 초기화
pnpm changeset init

# 1. 변경사항 설명 추가
pnpm changeset
# ? 어떤 패키지가 변경되었나요? → @myorg/ui, @myorg/utils
# ? 변경 유형은? → minor (새 기능)
# ? 변경 설명은? → Added new Button variant

# 2. .changeset/ 디렉토리에 파일 생성됨
cat .changeset/brave-dogs-run.md
# ---
# "@myorg/ui": minor
# "@myorg/utils": patch
# ---
#
# Added new Button variant

# 3. 버전 업데이트 (CI에서 실행)
pnpm changeset version

# 4. 배포
pnpm changeset publish

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [["@myorg/ui", "@myorg/hooks"]],
  "access": "restricted",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": ["@myorg/web", "@myorg/api"]
}

# .github/workflows/ci.yml
name: CI
on:
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: pnpm/action-setup@v2
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"

      - run: pnpm install --frozen-lockfile

      # Turborepo: 변경된 패키지만 빌드
      - run: turbo run build test lint --filter=...[origin/main]

      # 또는 Nx: 영향받는 프로젝트만
      # - run: npx nx affected -t build test lint

캐시 없이:
  lint (2분) + test (5분) + build (8분) = 15분

원격 캐시 히트:
  lint (0.1초) + test (0.2초) + build (0.3초) = 0.6초

실제 변경된 패키지만:
  lint (20초) + test (1분) + build (2분) = 3분 20초

# 매트릭스 전략으로 병렬 실행
jobs:
  detect:
    runs-on: ubuntu-latest
    outputs:
      packages: ${{ steps.filter.outputs.packages }}
    steps:
      - uses: actions/checkout@v4
      - id: filter
        run: echo "packages=$(turbo run build --filter=...[origin/main] --dry-run=json | jq -c '.packages')" >> $GITHUB_OUTPUT

  build:
    needs: detect
    runs-on: ubuntu-latest
    strategy:
      matrix:
        package: ${{ fromJson(needs.detect.outputs.packages) }}
    steps:
      - uses: actions/checkout@v4
      - run: turbo run build --filter=${{ matrix.package }}

# 모노레포에서의 Docker 빌드
FROM node:20-slim AS base
RUN corepack enable

FROM base AS pruned
WORKDIR /app
COPY . .
# turbo prune: 특정 앱과 의존성만 추출
RUN npx turbo prune @myorg/api --docker

FROM base AS installer
WORKDIR /app
# 의존성만 먼저 설치 (캐시 레이어)
COPY --from=pruned /app/out/json/ .
COPY --from=pruned /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
RUN pnpm install --frozen-lockfile

# 소스 복사 및 빌드
COPY --from=pruned /app/out/full/ .
RUN pnpm turbo run build --filter=@myorg/api

FROM base AS runner
WORKDIR /app
COPY --from=installer /app/apps/api/dist ./dist
COPY --from=installer /app/node_modules ./node_modules
CMD ["node", "dist/main.js"]

# .github/CODEOWNERS

# 전역 기본 소유자
* @org/platform-team

# 앱별 소유자
/apps/web/          @org/frontend-team
/apps/api/          @org/backend-team
/apps/mobile/       @org/mobile-team

# 패키지별 소유자
/packages/ui/       @org/design-system-team
/packages/utils/    @org/platform-team
/packages/auth/     @org/security-team

# 설정 파일
/tooling/           @org/dx-team
/.github/           @org/dx-team
/turbo.json         @org/dx-team

// .eslintrc.json
{
  "rules": {
    "@nx/enforce-module-boundaries": [
      "error",
      {
        "depConstraints": [
          {
            "sourceTag": "scope:web",
            "onlyDependOnLibsWithTags": ["scope:shared", "scope:web"]
          },
          {
            "sourceTag": "scope:api",
            "onlyDependOnLibsWithTags": ["scope:shared", "scope:api"]
          },
          {
            "sourceTag": "type:app",
            "onlyDependOnLibsWithTags": ["type:lib", "type:util"]
          },
          {
            "sourceTag": "type:lib",
            "onlyDependOnLibsWithTags": ["type:lib", "type:util"]
          }
        ]
      }
    ]
  }
}

# .github/workflows/auto-assign.yml
name: Auto Assign Reviewers
on:
  pull_request:
    types: [opened]

jobs:
  assign:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Auto assign based on changed files
        uses: kentaro-m/auto-assign-action@v2
        with:
          configuration-path: .github/auto-assign.yml

# 새 모노레포 저장소 생성
mkdir my-monorepo && cd my-monorepo
git init
pnpm init

# 기존 저장소를 서브디렉토리로 이동 (히스토리 보존)
git remote add -f web-repo https://github.com/org/web-app.git
git merge web-repo/main --allow-unrelated-histories

# git-filter-repo로 디렉토리 구조 변경
git filter-repo --to-subdirectory-filter apps/web

# pnpm workspace 설정
cat > pnpm-workspace.yaml << 'EOF'
packages:
  - "apps/*"
  - "packages/*"
EOF

# 루트 package.json 설정
# (위 4.3절 참조)

# 중복 코드를 공유 패키지로 추출
mkdir -p packages/shared-utils/src
# 공통 유틸 이동 및 패키지 설정

# Turborepo 또는 Nx 설정
pnpm add -D turbo -w
# turbo.json 설정 (위 6.2절 참조)

# Before: 모든 패키지 빌드 (15분)
pnpm -r run build

# After: 변경된 패키지만 (2분)
turbo run build --filter=...[origin/main]

# syncpack으로 의존성 버전 확인
npx syncpack list-mismatches
npx syncpack fix-mismatches

# Shallow clone
git clone --depth 1 https://github.com/org/monorepo.git

# Partial clone (blob 없이)
git clone --filter=blob:none https://github.com/org/monorepo.git

# Sparse checkout (특정 디렉토리만)
git clone --sparse https://github.com/org/monorepo.git
cd monorepo
git sparse-checkout set apps/web packages/ui

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}