npmユーザー向けに理解するpnpm

pnpm は、Node.js のパッケージマネージャーです。コマンドの見た目は npm にかなり近いですが、内部の依存管理が異なります。

npm を使ってきた人が最初に押さえるべきポイントは次の3つです。

速い
ディスク使用量が少ない
依存関係の不整合に気づきやすい

まず結論: npmと何が違う？

1. インストールの仕組み

npm
- プロジェクトごとに node_modules を展開する
pnpm
- パッケージ本体はグローバルストアに1回だけ保存
- 各プロジェクトの node_modules にはリンクを張る

この仕組みのおかげで、同じ依存を使うプロジェクトが多いほど pnpm の恩恵が大きくなります。

2. 依存解決の厳しさ

pnpm は「宣言していない依存」を参照しにくい構造です。

つまり、

たまたま動いていたコード
暗黙依存に頼ったコード

が早めに壊れてくれるため、結果的に健全な依存管理になります。

3. lockfileが異なる

npm: package-lock.json
pnpm: pnpm-lock.yaml

チームで使うときは、どちらかに統一します。

npmコマンドとの対応表

やりたいこと	npm	pnpm
依存を追加	`npm install axios`	`pnpm add axios`
開発依存を追加	`npm install -D typescript`	`pnpm add -D typescript`
依存を削除	`npm uninstall axios`	`pnpm remove axios`
スクリプト実行	`npm run build`	`pnpm build`
一時実行	`npx vitest`	`pnpm dlx vitest`
全依存インストール	`npm install`	`pnpm install`

pnpm run build でも動きますが、通常は pnpm build と短く書けます。

導入手順

Node.js には Corepack が同梱されているため、次の2コマンドで始められます。

corepack enable
corepack prepare pnpm@latest --activate

確認:

pnpm --version

既存npmプロジェクトをpnpmへ移行する

プロジェクト直下で実行:

rm -rf node_modules package-lock.json
pnpm install

これで pnpm-lock.yaml が作られます。

チーム開発では、README や CI のコマンドも npm から pnpm にそろえます。

workspaceを使うとさらに便利

モノレポの場合、pnpm の workspace は扱いやすいです。

例: pnpm-workspace.yaml

packages:
	- apps/*
	- packages/*

特定パッケージだけに依存追加:

pnpm --filter @myorg/web add zod

よくあるハマりどころ

npm用の手順が混ざる
- npm install を叩くと lockfile が混在しやすい
宣言漏れ依存でビルドが落ちる
- 実はこれが pnpm の良さ。必要な依存を package.json に追加する
ツールが node_modules の特殊構造を前提にしていない
- まずはツールを最新版に上げる

npmユーザー向けのおすすめ運用

新規プロジェクトは最初から pnpm にする
lockfile は pnpm-lock.yaml のみをコミットする
CI もローカルも同じコマンドに統一する
「暗黙依存を許さない」文化に寄せる

まとめ

pnpm は、npm の代替というより「npmに慣れた人が自然に移行できる改良版」に近いです。

日常的なコマンドはほぼ同じ
速度と容量効率が良い
依存管理が堅くなる

まずは1つの個人プロジェクトを pnpm 化して、体感をつかむのがおすすめです。

npmユーザー向けのpnpm入門