pnpm: Claude Code 활용 가이드

pnpmワークスペースでモノレポを구축する

pnpmは厳密な依存解決とディスク効率の良さで人気の패키지マネージャーです。ワークスペース機能を使えば、추가ツールなしでモノレポを관리할 수 있습니다。Claude Codeを활용して、pnpmワークスペースの구성を효율적으로進めましょう。

ワークスペースの初期설정

> pnpm workspacesでモノレポ를 생성해줘。
> 구성：
> - apps/web: React SPA
> - apps/admin: 관리画面
> - packages/ui: 共通컴포넌트
> - packages/config: 共通설정

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

// package.json (ルート)
{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "dev": "pnpm -r --parallel dev",
    "build": "pnpm -r build",
    "lint": "pnpm -r lint",
    "test": "pnpm -r test"
  },
  "devDependencies": {
    "typescript": "^5.5.0"
  }
}

패키지間の依存관리

> web앱からui패키지を参照する설정をして。
> TypeScriptのパス解決もセットアップして。

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

// packages/ui/package.json
{
  "name": "@myapp/ui",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": {
      "import": "./src/index.ts",
      "types": "./src/index.ts"
    }
  }
}

workspace:* プロトコルにより、常にローカルの패키지が参照されます。公開時には実際のバージョン番号に自動置換されます。

フィルタリングとスクリプト実行

pnpmのフィルタ機能で特定패키지のみを操作할 수 있습니다。

# 特定パッケージのdev実行
pnpm --filter @myapp/web dev

# 依存パッケージも含めてビルド
pnpm --filter @myapp/web... build

# 変更があったパッケージのみテスト
pnpm --filter "...[origin/main]" test

# 複数パッケージの指定
pnpm --filter "@myapp/web" --filter "@myapp/admin" build

Changesetsでバージョン관리

> changesetsを도입して、패키지の公開フローを整備して。

pnpm add -Dw @changesets/cli
pnpm changeset init

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

# 変更セットの作成
pnpm changeset

# バージョンの更新
pnpm changeset version

# 公開
pnpm -r publish --access public

.npmrcの최적화

> pnpmの설정を최적화して。strict-peer-depsと
> hoistの설정を적절하게して。

# .npmrc
strict-peer-dependencies=false
auto-install-peers=true
shamefully-hoist=false
link-workspace-packages=true
prefer-workspace-packages=true

shamefully-hoist=false はpnpmの厳密な依存解決を維持する重要な설정です。暗黙的な依存をコードから排除할 수 있습니다。

정리

pnpmワークスペースは、シンプルながら強力なモノレポ관리を実現します。Claude Code를 활용하면 依存関係の설정やCI구성もスムーズに進められます。モノレポ관리の実践가이드や依存관리の모범 사례도 함께 참고하세요.

pnpm의 상세 정보는pnpm공식 문서를 참고하세요.