pnpm

pnpm 開発

JavaScript および TypeScript プロジェクト向けの、高速でディスク容量効率に優れたパッケージマネージャーである pnpm のエキスパートです。

基本原則

• パッケージ管理には常に pnpm を使用します（npm や yarn は使用しません）
• pnpm の厳密な依存関係解決を活用して、セキュリティを高めます
• ディスク容量を効率的に使うため、コンテンツアドレス可能なストアを使用します
• 一貫性のあるロックファイル（pnpm-lock.yaml）を維持します

インストールとセットアップ

• pnpm をグローバルにインストールします：npm install -g pnpm
• または corepack を使用します：corepack enable && corepack prepare pnpm@latest --activate
• package.json で pnpm のバージョンを指定します：

  {
    "packageManager": "[email protected]"
  }
  

ワークスペースの設定

モノレポをセットアップするには、pnpm-workspace.yaml を作成します：

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

• glob パターンを使用して、ワークスペースパッケージの場所を定義します
• package.json を含む、一致したすべてのディレクトリがワークスペースパッケージになります

依存関係の管理

• 依存関係をインストールします：pnpm install
• 特定のワークスペースに依存関係を追加します：

  pnpm add lodash --filter @org/my-app
  pnpm add -D typescript --filter @org/my-lib
  

• 内部依存関係にはワークスペースプロトコルを使用します：

  {
    "dependencies": {
      "@org/shared-utils": "workspace:*",
      "@org/ui": "workspace:^"
    }
  }
  

• プロトコルのオプション：
  • workspace:* - 任意のバージョン。公開時に実際のバージョンに置き換えられます
  • workspace:^ - 互換性のあるバージョン
  • workspace:~ - パッチバージョンのみ

コマンドのフィルタリング

特定のパッケージでコマンドを実行します：

pnpm --filter @org/my-app dev
pnpm --filter "./apps/*" build
pnpm --filter "...@org/my-lib" test  # Include dependents
pnpm --filter "@org/my-lib..." build  # Include dependencies

• フィルターパターン：
  • --filter <package-name> - 特定のパッケージ
  • --filter "./path/*" - パスで指定
  • --filter "...<pkg>" - パッケージとその依存先
  • --filter "<pkg>..." - パッケージとその依存関係

スクリプトとタスクの実行

• ワークスペース全体でスクリプトを実行します：

  pnpm -r run build        # Run in all packages
  pnpm -r --parallel run dev  # Run in parallel
  pnpm -r --stream run test   # Stream output
  

• 共通操作のためにルートレベルのスクリプトを定義します：

  {
    "scripts": {
      "build": "pnpm -r run build",
      "dev": "pnpm --filter @org/web dev",
      "lint": "pnpm -r run lint",
      "test": "pnpm -r run test"
    }
  }
  

依存関係のホイスティング

.npmrc でホイスティングを設定します：

# Strict mode - no hoisting
hoist=false

# Selective hoisting
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*

# Shamefully hoist everything (not recommended)
shamefully-hoist=true

• 依存関係の分離を強化するには、厳密モードを優先します
• フラットな node_modules を必要とするツールには、パブリックホイスティングを使用します

ピア依存関係

.npmrc でピア依存関係の処理を設定します：

auto-install-peers=true
strict-peer-dependencies=false

• ピア依存関係の警告に適切に対処します
• 必要なピア依存関係を明確に記載します

オーバーライドと解決

ルートの package.json で依存関係をオーバーライドします：

{
  "pnpm": {
    "overrides": {
      "lodash": "^4.17.21",
      "[email protected]": "npm:bar@^2.0.0"
    }
  }
}

• セキュリティ上の脆弱性を修正するためにオーバーライドを使用します
• 問題のある推移的依存関係を固定します

ワークスペースの公開

• 公開可能なパッケージに適切なフィールドを設定します
• pnpm publish で公開します
• ワークスペースプロトコルの参照は実際のバージョンに置き換えられます

パフォーマンスの最適化

• Docker でのキャッシュを改善するため、pnpm fetch を使用します：

  COPY pnpm-lock.yaml ./
  RUN pnpm fetch
  COPY . ./
  RUN pnpm install --offline
  

• CI キャッシュ用にストアの場所を設定します
• CI 環境では --frozen-lockfile を使用します

ベストプラクティス

• pnpm-lock.yaml は必ずコミットします
• チーム全体で一貫した設定を行うには .npmrc を使用します
• 内部依存関係には workspace:* を優先します
• ルートの package.json は最小限に保ちます
• pnpm dedupe を使用してロックファイルを最適化します
• pnpm audit で定期的に監査します
• pnpm why <package> を使用して依存関係の問題をデバッグします
• 高度なタスク実行には Turborepo または Nx と連携します
• engine-strict=true を設定して、Node.js のバージョン要件を強制します