npm 完全ガイド：package.json・package-lock・ワークスペースからセキュリティ対策までの実務ベストプラクティス

NPM とは — 概要

NPM（Node Package Manager）は、Node.js 向けのパッケージ管理ツールおよびパッケージレジストリの総称です。開発者がライブラリやツールを公開・共有したり、プロジェクトの依存関係をインストール・管理したりするための仕組みを提供します。コマンドラインツール（npm CLI）と公開されている中央レジストリ（registry.npmjs.org）が組み合わさり、JavaScript/Node.js エコシステムの中心的役割を果たしています。

歴史と運営

npm は Node.js の普及とともに成長してきたツールで、2010年代から標準的なパッケージ管理手段として定着しました。2017 年に導入された package-lock.json や、以降のバージョンで追加されたワークスペース対応など、複数の重要な機能拡張が行われています。2020 年に GitHub（Microsoft 傘下）が npm 社を買収し、以降は GitHub のインフラやセキュリティ基盤との連携が進みています。

構成要素

• npm CLI：コマンドラインツール（例：npm install、npm publish、npm auditなど）。
• npm レジストリ：公開パッケージのホスティング（デフォルトは https://registry.npmjs.org/）。
• package.json：プロジェクトのメタデータ兼依存関係宣言ファイル。
• package-lock.json / npm-shrinkwrap.json：インストール結果のロックファイル。確定的な再現に利用。
• node_modules：実際にインストールされたパッケージ群の格納場所。

package.json の重要フィールド

package.json は npm エコシステムで中心的な役割を果たします。主なフィールドは次の通りです：

• name、version：パッケージの識別。
• description、repository、license：説明や著作権・公開情報。
• main、module、types：モジュールのエントリーポイント。
• scripts：テストやビルドなどのコマンド（pre / post フック付き）。
• dependencies、devDependencies：本番依存・開発依存。
• peerDependencies：消費側での同一ライブラリ共存を期待する依存。
• optionalDependencies：失敗しても良い依存。
• engines：Node.js のバージョン制約。
• files、exports：公開ファイルの制御やサブパス公開。
• type：ESM（"module"） / CJS（"commonjs"） の指定。

バージョニングと semver（セマンティックバージョニング）

npm の依存指定は SemVer（例：1.2.3）に基づいています。一般的な演算子の動作は次の通りです：

• ^1.2.3：互換性のある非メジャーアップデートを受け入れ（>=1.2.3 <2.0.0）。ただし 0.x 系では挙動が厳しくなり、^0.2.3 は <0.3.0 の範囲になります。
• ~1.2.3：パッチ更新のみ許容（>=1.2.3 <1.3.0）。
• 1.2.x や範囲指定：複雑な条件を指定可能。

依存関係解決はまずロックファイル（存在する場合）を尊重し、なければ range にマッチする最新の適合バージョンを選びます。

package-lock.json と npm ci

package-lock.json はインストールした正確なバージョン、解決 URL、integrity（ハッシュ）を記録します。CI／再現目的で使われ、npm ci コマンドはロックファイルに厳格に従ってクリーンインストールを行うため、ビルドの再現性が高くなります。ロックファイルのフォーマットは npm のバージョンにより進化しており、例えば npm 7 系で拡張されたフォーマット（v2 等）が導入されています。

node_modules のレイアウトと重複の扱い

npm は依存の平坦化（deduplication）を行い、できるだけ依存をルート近くに配置して重複を減らします（npm 3 以降の一般的な挙動）。ただし依存のバージョン競合や peerDependencies などによりネストが残ることがあります。pnpm のような代替パッケージマネージャは、パッケージをコンテンツアドレス化して大幅にディスク使用量とインストール時間を改善する手法をとっています。

ワークスペース（Monorepo）サポート

npm はワークスペース機能を導入し、Monorepo（複数パッケージを単一リポジトリで管理）を公式にサポートしています。ルートの package.json に workspaces フィールドを置くことで、依存解決やローカルリンク、複数パッケージの一括コマンド実行が可能になります。Yarn や pnpm にも同様の機能があり、ワークスペース間の選び方はプロジェクトの要求に依存します。

セキュリティとサプライチェーンリスク

npm は大規模なパッケージエコシステムゆえにサプライチェーン攻撃の対象になりやすいです。過去に悪意あるコードやトランジティブ依存で問題が発生した事例があります。対策として：

• npm audit／npm audit fix で既知の脆弱性を検出・自動修正を試みる。
• 公開パッケージのメンテナ情報や公開履歴を確認する。
• 2FA（二段階認証）を有効にしてパッケージ公開の安全性を高める。
• CI では npm ci とロックファイルを使い再現性を確保する。
• 署名やソースの確認、最小権限の原則に基づく依存の整理。

公開・配布のフロー

パッケージを公開する基本的な流れは次の通りです：ログイン（npm login）→ package.json を整備→ npm publish。Scoped（@scope/name）パッケージはデフォルトで private とする設定も可能で、公開時に --access public を指定して公開することが一般的です。アクセス制御やオーガニゼーション単位の管理もサポートされており、有料プランで private レジストリやチーム管理が利用されます。

npm の主なコマンド（実務でよく使うもの）

• npm install [pkg]：パッケージをインストール。
• npm ci：ロックファイルに基づくクリーンインストール（CI 向け）。
• npm update：依存を更新（semver 範囲内）。
• npm publish：パッケージ公開。
• npm login / logout：認証管理。
• npm audit：脆弱性スキャン、npm audit fix で自動修正試行。
• npm run