依存関係の「幽霊」を狩り尽くせ：npm/yarn/pnpmの腐敗を防ぐ静的解析パイプラインの構築
現代のフロントエンド開発において、`node_modules`はブラックボックス化しやすい聖域です。特に大規模プロジェクトやモノレポでは、いつの間にか「使っていない依存関係（幽霊）」や「`package.json`に記述がないのに動いている隠れ依存関係」が蔓延し、ビルドの肥大化や予測不能な実行時エラーを引き起こします。
本稿では、単なる「依存関係の整理」を超え、CI/CDパイプラインに組み込むことで「依存関係の腐敗を物理的に不可能にする」ための高度なアーキテクチャを伝授します。
—
1. 幽霊を見極める：depcheckの真の活用法
`depcheck`は単なる未使用パッケージの抽出ツールではありません。CIにおいて「依存関係の妥当性」を担保するための検閲官です。
なぜ `depcheck` が必要なのか
Node.jsのモジュール解決アルゴリズム（特にnpm/yarn v1のフラット化やpnpmのシンボリックリンク構造）は、本来必要な依存関係が間接的にインストールされていても動いてしまうという「仕様上の欠陥」を抱えています。これを許容すると、将来的にその間接依存が消えた瞬間に本番環境でクラッシュします。
実践：CIに組み込むための設定
`depcheck`を実行する際は、`.depcheckrc` を用意し、プロジェクト固有の特殊な依存関係（例: `eslint-plugin-` や `babel-plugin-`）を無視リストに入れるのが定石です。
// .depcheckrc
{
“ignores”: [
“eslint-plugin-“, // ESLint系はビルド時に明示しないことが多いため除外
“@types/”, // 型定義ファイルも同様にビルド生成物ではないため除外
“prettier” // 設定ファイルのみで参照されるツールを除外
],
“parsers”: {
“/.js”: “es6”,
“/.jsx”: “es6”,
“/.ts”: “typescript”
}
}
—
2. モノレポの混沌を制する：syncpackの戦略的活用
モノレポにおいて最も危険なのは「各パッケージ間で依存関係のバージョンが不整合を起こすこと」です。AパッケージとBパッケージでReactのバージョンが異なれば、将来的に予期せぬフックの競合や型エラーが発生します。
syncpackによる強制的なバージョン同期
`syncpack`は、単にバージョンを揃えるツールではなく、「ポリシーをコード化する」ためのツールです。
以下の設定ファイル（`.syncpackrc`）は、チーム開発において「勝手なバージョン上げ」を阻止するための鉄壁のルールとなります。
{
“dependencyTypes”: [“dev”, “prod”, “peer”], // すべての依存タイプを対象にする
“semverGroups”: [
{
“range”: “^”, // 常にキャレット記法で統一
“dependencies”: [“”], // 全てのパッケージを対象
“packages”: [“”]
}
],
“versionGroups”: [
{
“dependencies”: [“react”, “react-dom”], // React系は常にバージョンを強制一致
“packages”: [“”]
}
]
}
—
3. 開発スピードを極限まで引き上げる「神設定」と運用ルール
優秀なテックリードは、ツールを「自動化」するだけでなく「開発者の体験（DX）」に落とし込みます。
隠れたキーボードショートカットとCLI活用
ターミナルでの操作を最適化し、ツールへのアクセスを呼吸のように自然にします。
- pnpm + jq 連携: パッケージの依存関係を瞬時に調査するコマンド
# 特定のパッケージがどこで使われているかをツリーで表示 — 開発者のローカル環境でどれだけ頑張っても、人間はミスをします。以下のスクリプトをCIのLint工程に加えることで、依存関係の健全性を自動的に強制できます。 .github/workflows/lint.yml の抜粋 uses: actions/setup-node@v3 run: pnpm install # バージョン不一致があれば即座にCIを落とす # 未使用依存があれば警告し、CIをfailさせる（必要に応じて） — 依存関係の整理を「後でやる作業」と捉えてはいけません。それは「技術的負債の利子」です。 `depcheck`や`syncpack`をパイプラインに組み込むことは、チームに対して「このプロジェクトの規律はツールによって守られている」という強力なメッセージになります。ツールが人間を監視するのではなく、ツールが人間を「ミスから解放する」のです。 今日からあなたのプロジェクトの`package.json`を、ただのリストから「堅牢なソフトウェアの設計図」へと昇華させてください。それが、真にスケールするチームの第一歩です。
pnpm why
4. CI/CDへの統合：パイプラインを「守護神」にする
jobs:
dependency-check:
runs-on: ubuntu-latest
steps:
run: npx syncpack list-mismatches
run: npx depcheck終わりに：アーキテクトからのメッセージ