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": "pnpm@9.0.0"
  }
  

ワークスペース設定

モノレポセットアップ用に pnpm-workspace.yaml を作成：

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

• ワークスペースパッケージの場所を定義するのにグロブパターンを使用
• 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  # 依存パッケージを含む
pnpm --filter "@org/my-lib..." build  # 依存関係を含む

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

スクリプトとタスク実行

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

  pnpm -r run build        # すべてのパッケージで実行
  pnpm -r --parallel run dev  # 並列実行
  pnpm -r --stream run test   # 出力をストリーム配信
  

• 一般的な操作用にルートレベルのスクリプトを定義：

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

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

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

# 厳密モード - ホイスティングなし
hoist=false

# 選択的ホイスティング
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*

# すべてをホイスト（非推奨）
shamefully-hoist=true

• 依存関係の分離を良好にするため厳密モードを推奨
• フラットな node_modules が必要なツール用にパブリックホイスティングを使用

ピア依存関係

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

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

• ピア依存関係の警告に適切に対応
• 必要なピア依存関係を明確に文書化

オーバーライドと解決

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

{
  "pnpm": {
    "overrides": {
      "lodash": "^4.17.21",
      "foo@1.x": "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 と統合
• Node.js バージョン要件を強制するために engine-strict=true を設定