はじめに

これまで私は、プロジェクトの初期セットアップや環境構築の際に、npm installを「とりあえず実行」していました。

npm installは、package.jsonの情報をもとにライブラリをインストールするコマンドですが、そもそもその仕組みを理解できていなかったためです。

そこで今回は、package.jsonの中身や役割を整理しながら、「npm installで何が起きているのか」を自分なりに理解するために記事にしてみました。

package.jsonとは？

一言でいうと

プロジェクトの設計書 + ライブラリ管理 + コマンド管理ファイルです。

基本構造

まずは全体像から

{
  "name": "my-app",
  "version": "1.0.0",
  "dependencies": {
    "react": "^19.0.0"
  },
  "devDependencies": {
    "eslint": "^9.0.0"
  },
  "scripts": {
    "start": "node index.js"
  }
}

package.jsonは、このようにJSON形式で構成されており、キーと値の組み合わせで情報を管理しています。

それぞれの項目には役割があり、依存関係やコマンド、プロジェクト情報などを一つのファイルでまとめて管理できるようになっています。

主な役割

1. ライブラリ（依存関係）の管理

"dependencies": {
  "react": "^19.0.0"
}

このプロジェクトで使うライブラリを定義します。

npm install

を実行すると、ここに書かれたライブラリがすべてインストールされます。

2. 開発用ライブラリの管理

"devDependencies": {
  "eslint": "^9.0.0"
}

開発時のみ使うもの（Lint、テストなど）を管理します。

dependenciesとdevDependenciesの違い

種類	用途
dependencies	本番で使う
devDependencies	開発時のみ

3. scripts（コマンドのショートカット）

"scripts": {
  "start": "node index.js",
  "build": "webpack"
}

これにより

npm run start
npm run build

のようにコマンドを簡単に実行できます。
scriptsを使うことで、複雑なコマンドでも統一された方法で実行できるようになり、チーム開発でも同じ手順で作業できるようになります。

4. プロジェクト情報

"name": "my-app",
"version": "1.0.0"

アプリの名前やバージョンなどを管理します。

package-lock.jsonとの違い

よくセットで出てくるのが package-lock.json です。

役割の違い

ファイル	役割
package.json	使うライブラリを定義
package-lock.json	実際にインストールされたバージョンを固定

package.jsonではバージョンを範囲で指定することが多いため、インストールするタイミングによってバージョンが変わる可能性があります。
その結果、同じpackage.jsonを使っていても、人や環境によってインストールされるバージョンが異なり、動作に差が出ることがあります。

一方でpackage-lock.jsonがあることで実際にインストールするバージョンが具体的な数値で固定され、同じ環境を再現できるようになります。

まとめ

package.json → 何を使うかを決める
package-lock.json → 実際に使うバージョンを固定する

チーム開発では、同じ環境を再現するためにpackage-lock.jsonも一緒に管理します。

npm installすると何が起きる？

npm installを実行すると、主に次のような処理が行われます。

package.json をもとに必要なライブラリを確認する
package-lock.json があれば、その内容をもとにバージョンを決定する
ライブラリ本体と依存関係をダウンロードする
node_modules フォルダにインストールする

npm installは、package.jsonに書かれている情報をもとに「必要なものを全部揃える」コマンドです。
例えば

"dependencies": {
  "mermaid": "^11.0.0"
}

と書かれている場合、

mermaid本体をインストールする
mermaidが内部で使っているライブラリも一緒にインストールする

といった処理が自動で行われます。

補足知識

node_modulesはGitに含めない

node_modulesは容量が非常に大きく、ファイル数も膨大になります。

また、package.jsonとpackage-lock.jsonがあればnpm installによって再生成できるため、Gitには含めず .gitignore に追加するのが一般的です。

importはnode_modulesを参照している

import axios from "axios";

このように書くと、Node.jsは自動的にnode_modules内のaxiosを探しにいきます。

そのため、パスを明示しなくてもライブラリを利用することができます。

バージョン指定の書き方

ライブラリ名の右側にあるバージョンの「先頭（左端）」に記号を書くことで、どの範囲までアップデートを許可するかをnpmに伝えます。

"dependencies": {
  "mermaid": "^10.2.0"
}

このように書かれている場合、次のような意味になります。

^10.2.0（キャレット） → 10.2.0 以上、11.0.0 未満の範囲で最新が入る
~10.2.0（チルダ） → 10.2.x の範囲で最新が入る
10.2.0（記号なし） → 完全に固定

例えば、"^10.2.0"の場合、

10.3.0 → インストールされる
10.9.0 → インストールされる
11.0.0 → インストールされない

という動きになります。
チーム開発では、意図しないアップデートを防ぐためにバージョン指定の理解が重要です。

まとめ

package.json は、使用するライブラリやコマンドを管理する中心的なファイル
npm install は、package.jsonの情報をもとに必要なライブラリをインストールする
package-lock.json によって、同じバージョンを再現できる

これらを理解することで、環境構築やトラブル時の対応がしやすくなります。

参考文献

npm公式ドキュメント/package.json仕様

↓ 学習の参考にさせていただきました