基礎

npm入門|JavaScriptパッケージ管理の基本

JavaScript npm パッケージ管理

npm入門|JavaScriptパッケージ管理の基本

npmの基本的な使い方を解説。package.json、パッケージのインストール、npm scripts、バージョン管理まで学べます。

こんな人向けの記事です

  • npmの使い方を基礎から学びたい
  • package.jsonの書き方を理解したい
  • npm scriptsを活用したい

STEP 1npmとは(Node Package Manager)

npm(Node Package Manager)は、JavaScriptのパッケージ管理ツールです。Node.jsをインストールすると自動的に使えるようになります。世界最大のソフトウェアレジストリで、200万以上のパッケージが公開されています。

npmの3つの役割

役割 説明
パッケージ管理 外部ライブラリのインストール・更新・削除を行う
依存関係の解決 パッケージ同士の依存関係を自動で解決する
スクリプト実行 ビルドやテストなどのコマンドを統一的に実行する

npmのバージョン確認

ターミナル
# Node.jsのバージョン確認
node -v
# 出力例: v20.11.0

# npmのバージョン確認
npm -v
# 出力例: 10.2.4

# npm自体のアップデート
npm install -g npm@latest
ポイント
npmはNode.jsに同梱されています。Node.jsをインストールすれば、すぐにnpmが使えます。Node.jsのインストールにはnvm(Node Version Manager)の利用がおすすめです。

npmとyarn・pnpmの違い

ツール 特徴 ロックファイル
npm Node.js標準。最も広く使われている package-lock.json
yarn Facebook製。並列インストールが高速 yarn.lock
pnpm ディスク効率が良い。シンボリックリンクを活用 pnpm-lock.yaml

STEP 2package.jsonの構造

package.jsonはプロジェクトの設定ファイルです。プロジェクト名、バージョン、依存パッケージ、スクリプトなどを管理します。すべてのnpmプロジェクトの起点となるファイルです。

package.jsonの作成

ターミナル
# 対話形式でpackage.jsonを作成
npm init

# デフォルト設定で即座に作成(おすすめ)
npm init -y

package.jsonの主要フィールド

package.json
{
  "name": "my-project",
  "version": "1.0.0",
  "description": "プロジェクトの説明",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "build": "webpack --mode production",
    "test": "jest"
  },
  "keywords": ["javascript", "tutorial"],
  "author": "Your Name",
  "license": "MIT",
  "dependencies": {
    "express": "^4.18.2"
  },
  "devDependencies": {
    "nodemon": "^3.0.2",
    "jest": "^29.7.0"
  }
}

各フィールドの解説

フィールド 説明 必須
name パッケージ名。小文字、ハイフン区切り はい
version セマンティックバージョニング形式(例: 1.0.0) はい
scripts npm runで実行できるコマンドの定義 いいえ
dependencies 本番環境で必要なパッケージ いいえ
devDependencies 開発時のみ必要なパッケージ いいえ
main パッケージのエントリポイント いいえ
license ライセンスの種類 いいえ
注意
nameフィールドにはスペースや大文字を使えません。my-projectのように小文字とハイフンで記述してください。npmレジストリに公開する場合は、既存パッケージ名と重複しないよう注意が必要です。

STEP 3パッケージのインストール

npmの最も基本的な操作がパッケージのインストールです。npm installコマンドで外部ライブラリをプロジェクトに追加できます。

基本的なインストール

ターミナル
# パッケージをインストール(dependenciesに追加)
npm install express

# 省略形
npm i express

# 複数パッケージを同時にインストール
npm install express cors dotenv

dependencies と devDependencies

ターミナル
# 本番用パッケージ(dependencies に追加)
npm install express
# → "dependencies": { "express": "^4.18.2" }

# 開発用パッケージ(devDependencies に追加)
npm install --save-dev jest
npm install -D jest  # 省略形
# → "devDependencies": { "jest": "^29.7.0" }
分類 コマンド 用途の例
dependencies npm install パッケージ名 express, react, axios など本番で使うもの
devDependencies npm install -D パッケージ名 jest, eslint, webpack など開発時のみ使うもの
ポイント
npm install --save-dev(または-D)で追加されたパッケージは、本番環境でnpm install --productionを実行した際にはインストールされません。テストツールやリンターなど、開発時のみ必要なパッケージはdevDependenciesに入れましょう。

グローバルインストール

ターミナル
# グローバルにインストール(システム全体で使えるコマンド)
npm install -g typescript

# グローバルパッケージの一覧
npm list -g --depth=0

# グローバルパッケージの削除
npm uninstall -g typescript
グローバルインストールは最小限に
グローバルインストールはプロジェクトごとにバージョンを管理できません。基本的にはプロジェクトローカルにインストールし、npxで実行する方法が推奨されます(STEP6で解説)。

その他の操作コマンド

ターミナル
# package.jsonの全パッケージをインストール
npm install

# パッケージの削除
npm uninstall express

# パッケージの更新
npm update express

# 更新可能なパッケージの確認
npm outdated

# インストール済みパッケージの一覧
npm list --depth=0

package-lock.json とは

npm installを実行すると、package-lock.jsonが自動生成されます。このファイルは、インストールされたパッケージの正確なバージョンとその依存関係を記録しています。

package-lock.json の役割
チーム開発や CI/CD 環境で、全員が同じバージョンのパッケージを使えるようにするためのファイルです。必ずGitにコミットしてください。.gitignoreに追加してはいけません。
ターミナル
# CI環境ではこちらを使う(package-lock.jsonに従って正確にインストール)
npm ci
コマンド 用途 lock ファイル
npm install 開発時のインストール 更新される
npm ci CI/CD・本番デプロイ 変更されない(不一致時エラー)

STEP 4npm scripts

npm scriptsは、package.jsonscriptsフィールドにコマンドを定義し、npm runで実行する仕組みです。ビルド、テスト、リント、開発サーバーの起動など、プロジェクトのタスクを統一的に管理できます。

基本的な使い方

package.json
{
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js",
    "build": "webpack --mode production",
    "test": "jest",
    "lint": "eslint src/",
    "lint:fix": "eslint src/ --fix",
    "format": "prettier --write src/"
  }
}
ターミナル
# scriptsの実行
npm run dev
npm run build
npm run lint

# start, test, stop, restart は "run" を省略可能
npm start    # = npm run start
npm test     # = npm run test
ポイント
startteststoprestartはnpmの「ライフサイクルスクリプト」と呼ばれ、npm runを省略して直接実行できます。それ以外のカスタムスクリプトはnpm run スクリプト名で実行します。

pre / post フック

スクリプト名の前にprepostを付けると、自動的に前後に実行されます。

package.json
{
  "scripts": {
    "prebuild": "rm -rf dist",
    "build": "webpack --mode production",
    "postbuild": "echo 'ビルド完了!'"
  }
}
ターミナル
# npm run build を実行すると、以下の順で実行される
# 1. prebuild  → rm -rf dist
# 2. build     → webpack --mode production
# 3. postbuild → echo 'ビルド完了!'
npm run build

複数コマンドの連結

package.json
{
  "scripts": {
    "check": "npm run lint && npm run test",
    "dev:all": "npm run dev:server & npm run dev:client"
  }
}
演算子 動作 使用例
&& 前のコマンドが成功したら次を実行 lint && test
& 並列実行 server & client
|| 前のコマンドが失敗したら次を実行 test || echo "失敗"

実践的なscripts設定例

package.json(Reactプロジェクトの例)
{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview",
    "test": "vitest",
    "test:coverage": "vitest --coverage",
    "lint": "eslint . --ext .ts,.tsx",
    "lint:fix": "eslint . --ext .ts,.tsx --fix",
    "format": "prettier --write 'src/**/*.{ts,tsx,css}'",
    "check": "npm run lint && npm run test",
    "prepare": "husky install"
  }
}

STEP 5パッケージのバージョン管理(semver)

npmはセマンティックバージョニング(semver)というルールに従ってパッケージのバージョンを管理しています。バージョン番号の読み方と、^~の意味を理解することが重要です。

セマンティックバージョニングとは

バージョン番号はMAJOR.MINOR.PATCHの3つの数字で構成されます。

バージョン番号の読み方
  4  .  18  .  2
  │      │     └── PATCH: バグ修正(後方互換あり)
  │      └──────── MINOR: 機能追加(後方互換あり)
  └─────────────── MAJOR: 破壊的変更(後方互換なし)
変更の種類 バージョンの上がり方
バグ修正 PATCH が上がる 4.18.2 → 4.18.3
機能追加(互換性あり) MINOR が上がる 4.18.2 → 4.19.0
破壊的変更 MAJOR が上がる 4.18.2 → 5.0.0

バージョン指定の記号(^, ~, =)

package.jsonのバージョン指定には特殊な記号が使われます。それぞれの意味を正確に理解しましょう。

記号 意味 許容範囲
^(キャレット) MINORとPATCHの更新を許容 ^4.18.2 4.18.2 〜 4.x.x(5.0.0未満)
~(チルダ) PATCHの更新のみ許容 ~4.18.2 4.18.2 〜 4.18.x(4.19.0未満)
指定なし 完全一致 4.18.2 4.18.2のみ
* 任意のバージョン * すべて
>= 指定バージョン以上 >=4.18.2 4.18.2以上すべて
package.json
{
  "dependencies": {
    "express": "^4.18.2",   // MINOR・PATCHの更新OK(デフォルト)
    "lodash": "~4.17.21",   // PATCHの更新のみOK
    "moment": "2.29.4"      // 完全固定
  }
}
ポイント
npm installでパッケージを追加すると、デフォルトで^(キャレット)が付きます。多くの場合はこのままで問題ありませんが、特定バージョンに固定したい場合はnpm install express@4.18.2 --save-exactを使います。

バージョン管理の実践コマンド

ターミナル
# 特定バージョンをインストール
npm install express@4.18.2

# 最新版をインストール
npm install express@latest

# バージョンを完全固定してインストール
npm install express --save-exact

# 更新可能なパッケージを確認
npm outdated

# パッケージの全バージョンを確認
npm view express versions
メジャーバージョンアップに注意
^記号はメジャーバージョンの更新を許容しないため、通常は安全です。しかしnpm updateでメジャーバージョンを上げる場合は、破壊的変更がないか必ずCHANGELOGを確認してください。メジャーアップデートにはnpm install パッケージ名@latestを使います。

STEP 6npx の使い方

npxはnpm 5.2以降に同梱されているコマンド実行ツールです。パッケージをグローバルインストールせずに、一時的にダウンロードして実行できます。

npxの基本

ターミナル
# グローバルインストールなしでコマンドを実行
npx create-react-app my-app

# TypeScriptのコンパイル(ローカルインストール済みの場合)
npx tsc --init

# ESLintの初期設定
npx eslint --init

npxが便利な3つの場面

場面 説明
プロジェクト作成 npx create-react-app my-app 初回のみ使うツールをインストールせずに実行
ローカルパッケージの実行 npx jest node_modules/.bin/ のコマンドを直接実行
異なるバージョンの試用 npx node@18 -v 特定バージョンを一時的に使って確認

npx vs グローバルインストール

ターミナル
# グローバルインストールする場合(非推奨)
npm install -g create-react-app
create-react-app my-app

# npxを使う場合(推奨)
npx create-react-app my-app
# → 常に最新バージョンが使われる
npxを使うメリット
npxは常に最新バージョンのパッケージを実行するため、古いバージョンがグローバルに残る問題を防げます。特にcreate-react-appcreate-next-appのようなプロジェクト作成ツールは、npxでの実行が公式に推奨されています。

よく使うnpxコマンド

ターミナル
# Reactプロジェクトの作成
npx create-react-app my-app

# Next.jsプロジェクトの作成
npx create-next-app@latest my-app

# Viteプロジェクトの作成
npx create-vite@latest my-app

# TypeScriptの初期化
npx tsc --init

# ローカルサーバーの起動
npx serve dist

# パッケージの脆弱性チェック
npx npm-check-updates

まとめnpm の基本をマスターしよう

この記事で学んだnpmの基本を振り返りましょう。

  • npmはNode.jsのパッケージ管理ツール。node -vnpm -vで確認
  • package.jsonはプロジェクトの設定ファイル。npm init -yで作成
  • npm installでパッケージ追加。-Dで開発用、-gでグローバル
  • npm scriptsnpm runコマンドを定義。ビルドやテストを統一管理
  • semverでバージョン管理。^はMINOR許容、~はPATCH許容
  • npxでグローバルインストールなしにコマンドを実行
次のステップ
npmの基本を理解したら、ESLintやPrettierの設定、Webpackなどのバンドラーの利用に進みましょう。npm scriptsを活用して開発ワークフローを自動化すると、開発効率が大幅に向上します。