JavaScriptの基礎 - パッケージ管理

提供: MochiuWiki : SUSE, EC, PCB

概要

npm (Node Package Manager) は、Node.js に同梱される標準のパッケージマネージャーである。

npm Registryという世界最大級のソフトウェアレジストリを管理しており、250万以上のパッケージが公開されている。
JavaScriptおよびNode.jsのエコシステムにおいて、ライブラリや開発ツールの配布・管理の中心的な役割を担っている。

npmを利用することで、以下に示すことが可能になる。

npmで可能なこと
項目 説明
プロジェクトの依存パッケージの管理 package.jsonファイルに依存関係を記録して、チーム間で環境を統一する。
パッケージのインストール・更新・削除 コマンド1つで外部ライブラリの導入や管理ができる。
スクリプトの実行 ビルド、テスト、起動等の作業コマンドを定義して実行できる。
バージョン管理 セマンティックバージョニングにより、依存パッケージのバージョンを制御できる。



npmの基本

npmとは

npmは、Node.jsに標準同梱されるパッケージマネージャーであり、Node.jsをインストールすると自動的に利用可能になる。

npmの主な構成要素を以下に示す。

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ファイルで使用できる主要フィールドを示す。

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ファイルの役割を以下に示す。

ロックファイルのメリット
メリット 説明
再現性の確保
  • チームメンバーやCI/CD環境で全く同じバージョンの依存関係をインストールできる。
  • package.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を汚染せずにツールを利用できる。
また、常に最新バージョンのパッケージを実行する場合にも有用である。


関連情報



「https://mochiu.net/index.php?title=JavaScriptの基礎_-_パッケージ管理&oldid=14376」から取得