npm入門｜パッケージ管理の基本からscriptsまで

npm（Node Package Manager）は、JavaScriptのパッケージ管理ツールです。世界中の開発者が公開しているライブラリを簡単にインストールして使うことができます。この記事ではnpmの基本的な使い方をpackage.jsonの読み方からscriptsの活用まで解説します。

npmとは

npmはNode.jsに付属しているパッケージ管理ツールです。npmを使うと、他の開発者が作ったライブラリ（パッケージ）を自分のプロジェクトに追加したり、プロジェクトの依存関係を管理したりできます。

npmのインストール確認

Node.jsをインストールすると、npmも一緒にインストールされます。

# Node.jsのバージョン確認
node --version
# v22.x.x と表示されればOK

# npmのバージョン確認
npm --version
# 10.x.x と表示されればOK

Node.jsが入っていない場合は、公式サイト（https://nodejs.org/）からLTS版をダウンロードしてインストールしてください。

パッケージとは

パッケージとは、特定の機能を提供するJavaScriptのコードの集まりです。npm公式サイト（https://www.npmjs.com/）には、300万以上のパッケージが公開されています。

よく使われるパッケージの例を挙げます。

express: Webアプリケーションフレームワーク
axios: HTTPクライアント
lodash: ユーティリティ関数の集まり
dayjs: 日付操作ライブラリ

package.jsonの基本

package.jsonは、プロジェクトの設定と依存パッケージを記録するファイルです。JavaScriptプロジェクトの「設計書」のような役割を持ちます。

package.jsonの作成

# 新しいプロジェクトでpackage.jsonを作成
mkdir my-project
cd my-project
npm init -y

npm init -yを実行すると、デフォルト設定でpackage.jsonが作られます。

package.jsonの中身

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

主要なフィールドの意味は以下の通りです。

name: プロジェクト名
version: バージョン番号
description: プロジェクトの説明
main: エントリーポイントとなるファイル
scripts: コマンドのショートカット（後述）
dependencies: 本番環境で必要なパッケージ（npm installで自動追加）
devDependencies: 開発時のみ必要なパッケージ

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

npm installの基本

# パッケージをインストール（dependenciesに追加）
npm install axios

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

# 開発用パッケージをインストール（devDependenciesに追加）
npm install --save-dev nodemon eslint

インストールしたパッケージはnode_modulesフォルダに保存され、package.jsonにも記録されます。

dependenciesとdevDependencies

{
  "dependencies": {
    "axios": "^1.7.0",
    "express": "^4.21.0"
  },
  "devDependencies": {
    "nodemon": "^3.1.0",
    "eslint": "^9.0.0"
  }
}

dependenciesはアプリの動作に必要なパッケージ、devDependenciesはテストやビルドなど開発時のみ必要なパッケージです。

バージョン指定の読み方

"axios": "^1.7.0"
  ^        ↑ メジャー.マイナー.パッチ

^1.7.0  → 1.7.0以上 2.0.0未満（マイナー・パッチの更新を許容）
~1.7.0  → 1.7.0以上 1.8.0未満（パッチの更新のみ許容）
1.7.0   → 1.7.0のみ（完全固定）

^（キャレット）が最もよく使われます。互換性を保ちながら自動で最新版を使う設定です。

node_modulesとpackage-lock.json

node_modulesはパッケージの実体が入るフォルダです。サイズが大きくなるため、Gitで管理する対象から外します。

# .gitignore に追記
node_modules/

package-lock.jsonはインストールされたパッケージの正確なバージョンを記録するファイルです。チーム全員が同じバージョンを使えるよう、Gitで管理します。

# package.jsonとpackage-lock.jsonから依存パッケージを復元
npm install

npm scriptsの活用

scriptsとは

package.jsonのscriptsフィールドにコマンドを登録すると、npm run コマンド名で実行できます。

{
  "scripts": {
    "start": "node app.js",
    "dev": "nodemon app.js",
    "build": "webpack --mode production",
    "test": "jest",
    "lint": "eslint src/"
  }
}

scriptsの実行

# scriptsを実行
npm run dev
npm run build
npm run lint

# start と test は run を省略できる
npm start
npm test

scriptsの活用例

{
  "scripts": {
    "start": "node dist/index.js",
    "dev": "nodemon src/index.js",
    "build": "tsc",
    "prestart": "npm run build",
    "lint": "eslint src/",
    "format": "prettier --write src/"
  }
}

preをつけたスクリプト（prestart）は、対応するスクリプト（start）の前に自動で実行されます。同様にpostをつけると後に実行されます。

パッケージの管理操作

パッケージの更新と削除

# インストール済みパッケージの更新状況を確認
npm outdated

# パッケージを最新版に更新
npm update axios

# パッケージを削除
npm uninstall axios

グローバルインストール

プロジェクトではなく、PC全体で使うツールはグローバルにインストールします。

# グローバルにインストール
npm install -g typescript

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

# グローバルパッケージの削除
npm uninstall -g typescript

ただし、近年はグローバルインストールの代わりにnpxを使うことが推奨されています。

npxで一時的にパッケージを実行

# インストールせずに一度だけ実行
npx create-react-app my-app
npx eslint src/
npx prettier --write .

npxを使うと、パッケージをグローバルにインストールしなくても一時的にダウンロードして実行できます。

よくあるトラブルと対策

node_modulesの再インストール

依存関係のエラーが起きた場合は、node_modulesを削除して再インストールすると解決することがあります。

# node_modulesを削除して再インストール
rm -rf node_modules
npm install

権限エラー（macOS / Linux）

グローバルインストールで権限エラーが出る場合は、npmのディレクトリを変更します。

# npmのグローバルディレクトリを変更
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# PATHに追加（.bashrc や .zshrc に追記）
export PATH=~/.npm-global/bin:$PATH

バージョンの競合

異なるバージョンのNode.jsを使い分けたい場合は、nvm（Node Version Manager）の利用を検討してください。

# nvmでNode.jsのバージョンを切り替え
nvm install 22
nvm use 22
nvm list

まとめ

npmはJavaScriptのパッケージ管理ツールで、npm installでパッケージを追加し、package.jsonで依存関係を管理します。npm runでscriptsを実行できるため、開発ワークフローの効率化にも役立ちます。まずはnpm init -yで新しいプロジェクトを作り、実際にパッケージをインストールして使ってみてください。