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
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の主要フィールド
{
"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が自動生成されます。このファイルは、インストールされたパッケージの正確なバージョンとその依存関係を記録しています。
.gitignoreに追加してはいけません。
# CI環境ではこちらを使う(package-lock.jsonに従って正確にインストール)
npm ci
| コマンド | 用途 | lock ファイル |
|---|---|---|
npm install |
開発時のインストール | 更新される |
npm ci |
CI/CD・本番デプロイ | 変更されない(不一致時エラー) |
STEP 4npm scripts
npm scriptsは、package.jsonのscriptsフィールドにコマンドを定義し、npm runで実行する仕組みです。ビルド、テスト、リント、開発サーバーの起動など、プロジェクトのタスクを統一的に管理できます。
基本的な使い方
{
"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
start、test、stop、restartはnpmの「ライフサイクルスクリプト」と呼ばれ、npm runを省略して直接実行できます。それ以外のカスタムスクリプトはnpm run スクリプト名で実行します。
pre / post フック
スクリプト名の前にpreやpostを付けると、自動的に前後に実行されます。
{
"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
複数コマンドの連結
{
"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設定例
{
"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以上すべて |
{
"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
# → 常に最新バージョンが使われる
create-react-appやcreate-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 -vとnpm -vで確認 - package.jsonはプロジェクトの設定ファイル。
npm init -yで作成 - npm installでパッケージ追加。
-Dで開発用、-gでグローバル - npm scriptsで
npm runコマンドを定義。ビルドやテストを統一管理 - semverでバージョン管理。
^はMINOR許容、~はPATCH許容 - npxでグローバルインストールなしにコマンドを実行