JavaScriptの基礎 - パッケージ管理
概要
npm (Node Package Manager) は、Node.js に同梱される標準のパッケージマネージャーである。
npm Registryという世界最大級のソフトウェアレジストリを管理しており、250万以上のパッケージが公開されている。
JavaScriptおよびNode.jsのエコシステムにおいて、ライブラリや開発ツールの配布・管理の中心的な役割を担っている。
npmを利用することで、以下に示すことが可能になる。
| 項目 | 説明 |
|---|---|
| プロジェクトの依存パッケージの管理 | package.jsonファイルに依存関係を記録して、チーム間で環境を統一する。 |
| パッケージのインストール・更新・削除 | コマンド1つで外部ライブラリの導入や管理ができる。 |
| スクリプトの実行 | ビルド、テスト、起動等の作業コマンドを定義して実行できる。 |
| バージョン管理 | セマンティックバージョニングにより、依存パッケージのバージョンを制御できる。 |
npmの基本
npmとは
npmは、Node.jsに標準同梱されるパッケージマネージャーであり、Node.jsをインストールすると自動的に利用可能になる。
npmの主な構成要素を以下に示す。
| 構成要素 | 説明 |
|---|---|
| npm CLI | コマンドラインから操作するツール パッケージのインストール、スクリプトの実行等を行う。 |
| npm Registry | パッケージが公開されるオンラインリポジトリ デフォルトは、https://registry.npmjs.org |
| package.json | プロジェクトのメタデータと依存関係を定義するファイル |
npmのバージョンを確認する。
npm --version
Node.jsとともに最新版を使用することが推奨される。
npmの初期化
新しいプロジェクトでnpmを使用する場合、まず npm init コマンドでプロジェクトを初期化する。
初期化方法は以下に示す2通りがある。
- 対話的に初期化する方法
- プロジェクト名、バージョン、説明等を対話的に入力して、package.jsonファイルを生成する。
npm init
- デフォルト値で自動生成する方法
- 全ての項目にデフォルト値を使用して、package.jsonを生成する。
- nameはディレクトリ名、versionは1.0.0となる。
npm init -y
初期化後、プロジェクトのルートディレクトリにpackage.jsonファイルが生成される。
package.json
基本構造
package.jsonファイルは、JSON形式のファイルであり、プロジェクトの設定・依存関係の管理に使用する。
package.jsonには、name と version のみが必要である。
{
"name": "my-project",
"version": "1.0.0",
"description": "プロジェクトの説明",
"main": "index.js",
"scripts": {
"start": "node index.js",
"test": "jest"
},
"dependencies": {
"express": "^4.18.2"
},
"devDependencies": {
"jest": "^29.0.0"
}
}
主要フィールド
下表に、package.jsonファイルで使用できる主要フィールドを示す。
| フィールド | 必須 | 用途 | 説明 |
|---|---|---|---|
name |
必須 | プロジェクト識別 | パッケージ名 小文字・ハイフン区切りを推奨 |
version |
必須 | バージョン管理 | semver形式 (例: 1.0.0) |
description |
省略可 | メタデータ | パッケージの簡潔な説明 |
main |
省略可 | エントリーポイント | CommonJS形式のメインファイル |
module |
省略可 | ESM対応 | ESM形式のメインファイル |
type |
省略可 | モジュール形式 | "module" または "commonjs" を指定 |
exports |
省略可 | エクスポート設定 | 条件付きエクスポートの定義 |
scripts |
省略可 | コマンド定義 | 開発・テスト等のコマンドを定義 |
dependencies |
省略可 | 本番依存 | 本番環境で必要なパッケージ |
devDependencies |
省略可 | 開発依存 | 開発時のみ必要なパッケージ |
peerDependencies |
省略可 | ピア依存 | ホスト側が提供すべきパッケージ |
engines |
省略可 | 実行環境 | 必要なNode.jsバージョンの指定 |
license |
省略可 | ライセンス | MIT Apache-2.0 等 |
repository |
省略可 | リポジトリ | ソースコード管理の場所 |
scriptsフィールド
scripts フィールドには、プロジェクトで使用するコマンドを定義する。
定義したスクリプトは npm run <スクリプト名> で実行できる。
{
"scripts": {
"start": "node index.js",
"test": "jest",
"build": "webpack --mode production",
"dev": "webpack --mode development --watch",
"prebuild": "rimraf dist",
"postbuild": "echo 'ビルド完了'"
}
}
下表に、スクリプトの実行方法と特殊なスクリプト名を示す。
| コマンド | 説明 |
|---|---|
| npm start | start スクリプトを実行する。run プレフィックスが不要
|
| npm test | test スクリプトを実行する。run プレフィックスが不要
|
| npm run build | build スクリプトを実行する。run プレフィックスが必要
|
| npm run dev | dev スクリプトを実行する。
|
pre / post スクリプトについて以下に示す。
スクリプト名に pre または post プレフィックスを付けると、自動的に前後に実行される。
例えば、build を実行した場合、prebuild -> build -> postbuild の順に自動実行される。
依存関係の管理
dependencies
dependencies は本番環境で動作するために必要なパッケージを定義するフィールドである。
パッケージを dependencies に追加するには以下のコマンドを使用する。
npm install express npm install express axios
インストール後、package.jsonファイルの dependencies に自動で追加される。
{
"dependencies": {
"axios": "^1.6.0",
"express": "^4.18.2"
}
}
dependencies の代表的なパッケージを以下に示す。
- express
- Node.jsのWeb フレームワーク
- axios
- HTTPクライアントライブラリ
- react
- UIライブラリ
devDependencies
devDependencies は開発時のみ必要なパッケージを定義するフィールドである。
テストフレームワーク、リンター、バンドラー等、本番環境には含めないパッケージを管理する。
パッケージを devDependencies に追加するには以下のコマンドを使用する。
npm install --save-dev jest npm install -D jest eslint webpack
本番環境でのみ依存関係をインストールする場合は以下のコマンドを使用する。
npm install --production
devDependencies の代表的なパッケージを以下に示す。
- jest
- JavaScriptテストフレームワーク
- eslint
- コード品質チェックツール
- webpack
- モジュールバンドラー
- typescript
- TypeScriptコンパイラ
peerDependencies
peerDependencies は、プラグインやライブラリがホスト側に期待するパッケージを定義するフィールドである。
ライブラリを開発する場合、利用者のプロジェクトに既にインストールされていることを前提とするパッケージを指定する。
{
"peerDependencies": {
"react": ">=17.0.0",
"react-dom": ">=17.0.0"
}
}
npm v7以降では、peerDependencies に記載されたパッケージが自動的にインストールされる。
npm v6以前では、警告が表示されるのみで自動インストールは行われなかった。
dependenciesの使い分け
下表に、3種類の依存関係の使い分けを示す。
| 種別 | インストールコマンド | 本番環境 | 使用例 |
|---|---|---|---|
dependencies |
npm install <パッケージ名> | 含まれる | express, react, axios |
devDependencies |
npm install --save-dev <パッケージ名> | 含まれない | jest, eslint, webpack |
peerDependencies |
ホスト側が提供 | ホスト側管理 | フレームワーク依存のプラグイン |
セマンティックバージョニング
バージョン番号の構造
セマンティックバージョニング (Semantic Versioning / semver) は、バージョン番号の付け方に関する仕様である。
npm パッケージのバージョン管理において標準的に使用される。
バージョン番号は MAJOR.MINOR.PATCH の形式で表される。
例: 1.2.3
下表に、各番号の意味を示す。
| バージョン番号 | 説明 |
|---|---|
| MAJOR (メジャー) | 後方互換性のない破壊的変更が行われた場合にインクリメントする。 例: API の仕様変更、機能の削除 |
| MINOR (マイナー) | 後方互換性を保ちながら新機能が追加された場合にインクリメントする。 例: 新しい関数やオプションの追加 |
| PATCH (パッチ) | 後方互換性を保ちながらバグが修正された場合にインクリメントする。 例: バグ修正、セキュリティパッチ |
バージョン範囲指定
package.jsonファイルでパッケージのバージョンを指定する時、範囲を指定する記号を使用できる。
| 記号 | 例 | 範囲 | 説明 |
|---|---|---|---|
^ (キャレット) |
^1.2.3 | 1.2.3〜2.0.0未満 | MINOR / PATCH の更新を許可 (npm install時のデフォルト) |
~ (チルダ) |
~1.2.3 | 1.2.3〜1.3.0未満 | PATCHの更新のみ許可 |
>= |
>=1.2.3 | 1.2.3〜 | 指定バージョン以上の全バージョン |
< |
<1.2.3 | 1.2.2以下 | 指定バージョン未満の全バージョン |
= |
=1.2.3 | 1.2.3のみ | 完全一致 |
* |
* | 全バージョン | バージョンを限定しない |
package-lock.json
package-lock.jsonファイルは、プロジェクトの依存関係の正確なバージョンを記録するロックファイルである。
npm install を実行するたびに自動生成・更新される。
package-lock.jsonファイルの役割を以下に示す。
| メリット | 説明 |
|---|---|
| 再現性の確保 |
|
| セキュリティ | 意図しないバージョンアップによる問題を防ぐことができる。 |
| インストール速度の向上 | ロックファイルを参照することにより、バージョン解決の処理を省略できる。 |
package-lock.jsonファイルは、gitリポジトリに含めて共有することが推奨される。
node_modulesディレクトリは、gitの管理対象外 (.gitignoreファイルに追加) とする。
よく使用するコマンド
パッケージのインストール
パッケージのインストールに使用するコマンドを以下に示す。
# package.jsonファイルの依存関係を全てインストール npm install npm i
# 特定のパッケージをインストール (dependenciesフィールドに追加) npm install <パッケージ名> npm i <パッケージ名>
# devDependenciesにインストール npm install --save-dev <パッケージ名> npm i -D <パッケージ名>
# グローバルにインストール npm install -g <パッケージ名>
# 特定のバージョンを指定してインストール npm install <パッケージ名>@1.2.3
パッケージの更新と削除
パッケージの更新・削除に使用するコマンドを以下に示す。
# 全パッケージを更新 (package.jsonファイルのバージョン範囲内で) npm update
# 更新可能なパッケージを一覧表示 npm outdated
# パッケージをアンインストール npm uninstall <パッケージ名>
スクリプトの実行
package.jsonファイルの scripts フィールドに定義したコマンドを実行する。
# startスクリプトを実行 npm start
# testスクリプトを実行 npm test
# 任意のスクリプトを実行 npm run <スクリプト名>
# 定義済みスクリプトの一覧を表示 npm run
パッケージ情報の確認
パッケージや依存関係の情報を確認するコマンドを以下に示す。
# インストール済みパッケージの一覧を表示 npm list npm ls
# パッケージの詳細情報を表示 (Registry に公開されている情報) npm info パッケージ名
# セキュリティ脆弱性の確認 npm audit
# 脆弱性の自動修正 npm audit fix
npxコマンド
npxは、npm v5.2.0以降に同梱されるコマンド実行ツールである。
パッケージをグローバルにインストールすることなく、一時的にパッケージを実行できる。
npxの主な用途を以下に示す。
- プロジェクトの雛型生成
- グローバルインストールなしに、最新のプロジェクト生成ツールを実行できる。
npx create-react-app my-app npx create-next-app@latest my-next-app
- ローカルパッケージのコマンド実行
- node_modules/.bin に存在するコマンドを実行できる。
npx eslint src/ npx tsc --version
- 一時的なツールの実行
- インストールせずにCLIツールを試したり、1度だけ使用したりできる。
npx http-server npx serve .
npxを使用することにより、グローバルのnode_modulesを汚染せずにツールを利用できる。
また、常に最新バージョンのパッケージを実行する場合にも有用である。
関連情報
