Monorepo & Package 관리 학습 일지

  19  .  1  .  0
  ↑      ↑     ↑
Major  Minor  Patch

19.0.0 → 19.0.1  (Patch: 메모리 누수 수정)
19.0.0 → 19.1.0  (Minor: 새 훅 추가, 기존 코드 유지)
18.0.0 → 19.0.0  (Major: forwardRef 제거, use() 추가 등)

^19.0.0  →  19.0.0 이상, 20.0.0 미만
^15.5.6  →  15.5.6 이상, 16.0.0 미만
^3.2.0   →  3.2.0  이상, 4.0.0  미만

~19.0.0  →  19.0.0 이상, 19.1.0 미만
~15.5.6  →  15.5.6 이상, 15.6.0 미만

"react": "19.0.0"  →  딱 이 버전만

"^0.8.0"  →  0.8.x만 허용  (0.9.0 불가!)

3월에 pnpm i  →  registry 최신: react@19.0.3 설치
4월에 pnpm i  →  registry 최신: react@19.1.0 설치

pnpm-lock.yaml: react 19.0.3 고정
→ 이후 누가 pnpm i 해도 항상 19.0.3 설치

kodeflo-monorepo/
├── pnpm-workspace.yaml      ← 워크스페이스 선언
├── pnpm-lock.yaml           ← 단일 lockfile (모든 앱 공유, 388KB)
├── package.json             ← 루트 (turbo, eslint, husky 등)
├── apps/
│   ├── admin/               (@kodeflo-admin-next)
│   ├── adv/                 (@kodeflo-adv-next)
│   ├── marketer/            (@kodeflo-marketer-next)
│   ├── partner-admin/
│   └── partner-marketer/
└── packages/
    ├── config/
    ├── shared/
    └── ui/

packages:
  - 'apps/*'
  - 'packages/*'

[1] pnpm-workspace.yaml 읽기
    → "apps/*, packages/*" 멤버 목록 수집
 
[2] 모든 멤버의 package.json 로드
    → 앱 + 패키지 + 루트 전체 package.json 병합
 
[3] 의존성 그래프 계산
    → 각 요구 범위를 만족하는 버전을 레지스트리 조회
    → peer dep 조합 계산 (동일 패키지도 peer 조합 다르면 별도 인스턴스)
 
[4] lockfile과 비교
    → --frozen-lockfile: 불일치 시 실패 (CI용)
    → 일반 실행: lockfile 갱신
 
[5] 중앙 store에 tarball 다운로드
    → ~/.pnpm-store/v3/files/<hash> (content-addressable)
    → 전 프로젝트 공유, 디스크 1벌
 
[6] node_modules 구성
    → store → hardlink → symlink 3단 링크
    → 각 앱/패키지의 node_modules는 심링크 뷰

# 전체 설치 (루트에서만)
pnpm install
 
# 특정 앱에만 패키지 추가
pnpm add <pkg> --filter @kodeflo/marketer
 
# 특정 앱 dev 실행
pnpm dev:marketer
 
# 특정 패키지가 어디서 왜 설치됐는지 확인
pnpm why <pkg> --filter @kodeflo/marketer

lockfileVersion: '9.0'
 
# Section 1: 각 workspace 멤버의 요구사항
importers:
  .:                                       # 루트
    devDependencies:
      turbo:
        specifier: ^2.5.0
        version: 2.5.0
 
  apps/admin:
    dependencies:
      '@chakra-ui/react':
        specifier: 3.28.1
        version: 3.28.1(@emotion/react@11.14.0)(...)
      '@kodeflo/shared':
        specifier: workspace:*
        version: link:../../packages/shared   # ← workspace 내부 링크
      next:
        specifier: ^15.5.6
        version: 15.5.6(react@19.0.0)(...)
 
  apps/marketer:
    dependencies:
      next:
        specifier: ^15.5.6
        version: 15.5.6(react@19.0.0)(...)    # ← admin과 동일 해시 공유
 
# Section 2: 패키지 풀 (실제 tarball 해시 기록)
packages:
  next@15.5.6:
    resolution:
      integrity: sha512-...
      tarball: https://registry.npmjs.org/next/-/next-15.5.6.tgz
 
  react@19.0.0:
    resolution:
      integrity: sha512-...

~/.pnpm-store/v3/files/                      [1단계: 전역 store]
  00/2a7...                                   ← react@19 실제 파일 (hardlink 소스)
  4f/b81...                                   ← next@15 실제 파일
 
kodeflo-monorepo/
├── node_modules/
│   └── .pnpm/                                [2단계: 가상 저장소]
│       ├── react@19.0.0/
│       │   └── node_modules/
│       │       └── react/                    ← store에서 hardlink
│       ├── next@15.5.6_react@19.0.0/         ← peer dep 조합별 폴더
│       │   └── node_modules/
│       │       ├── next/                     ← hardlink
│       │       └── react -> ../../react@19.0.0/node_modules/react
│       └── @kodeflo+shared/
│           └── node_modules/
│               └── @kodeflo/shared -> ../../../../packages/shared
│
├── apps/marketer/
│   └── node_modules/                         [3단계: 앱별 평면 뷰]
│       ├── react -> ../../../node_modules/.pnpm/react@19.0.0/node_modules/react
│       ├── next  -> ../../../node_modules/.pnpm/next@15.5.6_.../node_modules/next
│       └── @kodeflo/
│           └── shared -> ../../../../packages/shared   ← 원본 직접 참조
│
└── packages/shared/                          ← 실제 소스 (수정하면 즉시 반영)

apps/marketer/node_modules/@kodeflo/shared
  → ../../../../packages/shared   (실제 소스 폴더)

pnpm add date-fns --filter @kodeflo/marketer

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],   // 의존 패키지 먼저 빌드
      "outputs": [".next/**"]    // 캐시 대상
    },
    "dev": {
      "cache": false,            // dev는 캐시 안 함
      "persistent": true
    },
    "type-check": {
      "dependsOn": ["^build"]
    }
  }
}

첫 번째 빌드: 실제 빌드 실행 (30초)
두 번째 빌드: cache hit → 즉시 완료 (1초)

pnpm dev              # 전체 앱 dev (병렬)
pnpm dev:marketer     # marketer만 dev
pnpm build            # 전체 빌드 (의존성 순서 자동 결정)
pnpm type-check       # 전체 앱 타입 체크 (병렬)

apps/admin/src/utils/format-phone.ts
apps/marketer/src/utils/format-phone.ts  ← 중복!

kodeflo-monorepo/
├── apps/
│   ├── admin/
│   └── marketer/
└── packages/
    ├── ui/          ← 공유 컴포넌트
    └── utils/       ← 공유 유틸

// apps/marketer/package.json
{
  "dependencies": {
    "@kodeflo/ui": "workspace:*"
  }
}

packages:
  - 'apps/*'
  - 'packages/*'    ← 공유 패키지 추가

semver      →  버전 번호의 의미와 범위 선언 규칙
lockfile    →  실행 시점 무관하게 버전 고정 (재현 가능한 빌드)
importers   →  lockfile 내 각 앱의 의존성 요구사항 섹션
packages    →  lockfile 내 실제 tarball 해시 풀 (중복 없음)
3단 링크    →  store(hardlink) → .pnpm(가상 저장소) → 앱 node_modules(symlink)
workspace:* →  npm 레지스트리 우회, 내부 패키지 원본 직접 참조
turborepo   →  병렬 실행 + 캐싱으로 빌드 효율화
packages/   →  앱 간 코드 중복 제거