Node.jsメモ: package.json による依存パッケージの管理方法まとめ

Node.js アプリケーションが使用する依存パッケージの情報は、package.json というファイルに記述します。

package.json ファイルのひな型を生成する (npm init)

下記のコマンドを実行すると、対話形式で package.json ファイルを作成することができます。

$ npm init

何も入力せずに Enter を連打していくと、以下のようなファイルが生成されます。

{
  "name": "sample",
  "version": "0.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": "",
  "author": "",
  "license": "BSD"
}

すでにカレントディレクトリに package.json がある場合でも、npm init は、単純な上書きはしないで、足りないプロパティだけ補ってくれます。 副次的な作用として、フォーマットの整形にも使えます。

最小限の package.json

Node.js アプリケーションのマニフェストファイルである package.json には、最低限以下のような情報を記述しておきます。

{
  "name": "my-app",
  "version": "0.0.1",
  "private": true,
  "dependencies": {
    "express": "3.2.x",
    "jade": "*"
  }
}

アプリの名前 (name)、バージョン (version)、npm registry に公開しないこと ("private": true)、依存するモジュール (dependencies) などを記載しています。

依存パッケージは dependencies プロパティで指定する

package.json ファイルの dependencies プロパティには、現在開発中の Node パッケージ（アプリケーション）が依存するパッケージを列挙しておくことができます。 下記の例では、このパッケージ（アプリ）を使用するには、request パッケージと request-promise パッケージが必要であることを示しています（バージョンの指定方法は後述）。

{
  "name": "myapp",
  // ...
  "dependencies": {
    "request": "^2.88.0",
    "request-promise": "^4.2.2"
  }
}

カレントディレクトリにこの package.json ファイルがある状態で、下記のように実行すると、dependencies プロパティに列挙された依存パッケージが node_modules ディレクトリに自動的にインストールされます。

$ npm install

正確には、devDependencies プロパティに列挙された依存パッケージも一緒にインストールされます（詳細は後述）。

バージョンの指定方法

バージョンの指定方法にはいろいろありますが、よく使われるのは下記のような指定方法です。

1.2.3

指定したバージョンをインストールします。

>=1.2.3 <1.3.0

指定した範囲のうち最新のものをインストールします。

1.2.x

x の位置以下のレベルのバージョンは問わずにインストールします。

• 1.2.x → >=1.2.0 < 1.3.0
• 1.x → >=1.0.0 <2.0.0

^1.2.3

後方互換性のある（だろうと思われる）バージョンのうち、最新のバージョンをインストールします。 オススメの指定方法です。 npm install --save <pkg> でパッケージをインストールした場合、このバージョン指定方法で package.json の dependencies プロパティの値が更新されます。

major、minor、patch レベルのバージョンを左から見て、最初に 0 じゃない数値がみつかったらそこのバージョンを固定し、それより下のレベルのバージョンが更新されます。

• ^1.2.3 → >=1.2.3 <2.0.0
• ^0.2.3 → >=0.2.3 <0.3.0
• ^0.0.3 → >=0.0.3 <0.0.4
• ^1.2.3-beta.2 → >=1.2.3-beta.2 <2.0.0 （1.2.3 も含む）
• ^0.0.3-beta → >=0.0.3-beta <0.0.4 （0.0.3 も含む）
• ^1.2.x → >=1.2.0 <2.0.0
• ^0.0.x → >=0.0.0 <0.1.0
• ^0.0 → >=0.0.0 <0.1.0
• ^1.x → >=1.0.0 <2.0.0
• ^0.x → >=0.0.0 <1.0.0

ちなみに大文字の X でも OK。

~1.2.3

1.2.3 とバージョン固定で指定する方法に似ていますが、下位レベルの更新だけを受け入れます。 つまり、軽微な変更だけを許可する指定方法です。

minor レベルのバージョンが指定されている場合は、patch レベルのバージョン更新のみを許可します。

• ~1.2.3 → >=1.2.3 <1.3.0
• ~0.2.3 → >=0.2.3 <0.3.0
• ~1.2 → >=1.2.0 <1.3.0 （1.2.x と同じ）
• ~0.2 → >=0.2.0 <0.3.0 （0.2.x と同じ）
• ~1.2.3-beta.2 → >=1.2.3-beta.2 <1.3.0 （1.2.3 も含む）

major レベルのバージョンしか指定されていない場合は、minor レベル以下のバージョン更新を許可します。

• ~1 → >=1.0.0 <2.0.0 （1.x と同じ）
• ~0 → >=0.0.0 <1.0.0 （0.x と同じ）

* or ""

どのバージョンでも OK。 ようするに必ず最新バージョンのパッケージをインストールするという指定です。

dependencies プロパティと devDependencies プロパティ

開発時（テスト時）のみ使用するパッケージの依存関係は、dependencies プロパティではなく、devDependencies プロパティに記述します。 dependencies プロパティの方には、そのパッケージ（やアプリ）を使用するユーザ環境で必要なパッケージのみを列挙してください。

パッケージそのものの開発者は、ローカルディレクトリに package.json ファイルがある状態で、次のようなコマンドを実行して依存パッケージを一括インストールするはずです。 この場合は、dependencies プロパティに書かれた依存モジュールに加え、devDependencies プロパティに書かれた依存モジュールも一緒にインストールされます。

$ npm install

dependencies プロパティに列挙された依存モジュールのみをインストールしたい場合は、下記のように --production オプションを使用します。

$ npm install --production

パッケージのインストール時に package.json を更新する

npm install コマンドを使ってパッケージをインストールするときに、--save オプションを付加すると、package.json の dependencies プロパティの記述も更新することができます。

$ npm install --save <pkg>

開発のみに使用するパッケージの依存情報 (devDependencies) を追加するときは、--save オプションの代わりに --save-dev オプション を使用します。

$ npm install --save-dev <pkg>

package.json の書式、説明を確認する (npm help json)

Node パッケージに関する情報（モジュールの名前や説明、依存パッケージなどの情報）は、package.json というファイルに記述します。 以下のコマンドで、package.json の書き方のヘルプを見ることができます（Web ブラウザ上で表示されます）。

$ npm help json

表示される内容は、下記のサイトのものと同様です。

• https://docs.npmjs.com/files/package.json

参考

• package.json - dependencies
  • package.json ファイルの dependencies プロパティに関する説明。
• npm-semver - The semantic versioner for npm
  • npm コマンドは、この semver というモジュールを使って、バージョン情報をパースしています。