【初心者向け】package.json / package-lock.json / node_modules を整理してみた

Node.js や npm を使っていると必ず出てくる

• package.json
• package-lock.json
• node_modules

最初はどれが何をしているのか混乱したので、自分なりに整理してみました。

1. package.json：依存関係の設計図

package.json はプロジェクトの基本情報と依存関係をまとめたファイル。

package.json

{
  "name": "my-app",
  "version": "1.0.0",
  "dependencies": {
    "react": "^18.2.0",
    "next": "13.4.0"
  },
  "scripts": {
    "dev": "next dev"
  }
}

• "react": "^18.2.0" → 「18.2.0 以上 19 未満ならOK」という意味
• 実際にどのバージョンが入るかはまだ決まっていない

2. package-lock.json：依存関係のスナップショット

npm install を実行すると自動で作られるファイル。

ここには 実際にインストールされた正確なバージョン が記録されている。

package-lock.json

"react": {
  "version": "18.2.0",
  "resolved": "https://registry.npmjs.org/react/-/react-18.2.0.tgz",
  "integrity": "sha512-..."
}

これがあるおかげで、チームメンバー全員が同じ環境を再現できる。

※npm install は lock を優先するのか？

基本的には lock が優先される。

• package.json と package-lock.json が一致しているとき → lock に書かれたバージョン通りにインストール
• package.json を変更したとき（例：新しいライブラリ追加） → その変更を反映して lock を更新
• lock が存在しないとき → package.json をもとに新しく lock を生成

※Lock ファイルだけでインストールできるのか？

• npm v6 → package-lock.json だけでも npm ci で再現できたのこと
• npm v7 以降 → package.json が必須になった

実際には 両方セットで管理するのが定石

3. node_modules：実際の部品倉庫

npm install でダウンロードされたパッケージの本体が入るフォルダ。

中には自分が指定したライブラリだけじゃなく、そのライブラリがさらに依存しているものも全部入っている。

node_modules/
├── next/
├── react/
├── react-dom/
└── styled-jsx/

• めちゃくちゃ巨大になることもある（数百 MB とか…）
• 消しても OK → npm install すれば再生成される
• Git に上げる必要はないので .gitignore に入れるのが普通

4. npm install と npm ci の違い

コマンド	動き	使いどころ
npm install	package.json と package-lock.json を見て依存関係を解決。lock がなければ生成	普段の開発
npm ci	package-lock.json 通りにインストール。node_modules を一度消してクリーンに入れ直す	CI/CD や本番環境

5. まとめ

• package.json → 依存関係の設計図（範囲指定）
• package-lock.json → 実際に入ったバージョンの記録（固定）
• node_modules → 実際にダウンロードされたもの（倉庫）
• 開発では npm install、本番では npm ci が安心
• lock だけでインストールできた時代もあったけど、今は package.json とセットで考えるのが基本