package.json の 仕様 (日本語)

必須

package.json にとって name と version はもっとも重要なフィールドです。 これらは必須項目で、これらが指定されていないと パッケージ をインストールできません。 name と version の組み合わせでパッケージを一意に特定します。 パッケージの変更は version の変更も伴うべきものです。

ルール：

• 214文字以下でなければなりません。この文字数にはスコープ文字列も含まれます。
• ドット . または アンダースコア _ から始めることはできません。
• 新しいパッケージ名には大文字を含んではいけません。
• nameフィールドは URL、コマンドライン引数、フォルダ名の一部になります。そのため、安全でないURL文字を含められません。

ヒント：

• Nodeコアモジュールと同じ名前を使ってはいけません。
• "js"や"node"を名前の中に含んではいけません。package.json を記載している時点で js であり、 "engine" フィールドを利用することで エンジン を特定することができます。
• nameフィールドは require() の引数に渡されるので、ある程度短くも説明的であるべきです。
• 使おうとしている名前がすでに使われているかどうか、npmレジストリを調べてみてください。
  https://www.npmjs.com/

必須

version は npm の依存として含まれている node-semver で構文解析可能でなければなりません。

バージョン番号に関する詳細は semver を参照してください。

プロジェクトホームページへのURL。

注意：

"homepage" は "url"とは異なりませ宇。 もし "url" フィールドを設定する場合、レジストリはパッケージが別の場所に移されたのでリダイレクトしようとします。

バグトラッカーへの URL または / かつ バグ連絡先となる メールアドレス。 これらの値はパッケージ利用者がバグに遭遇したときに役立ちます。

サンプル：

{
  "url": "https://github.com/owner/project/issues",
  "email": "project@hostname.com"
}

"url" と "email" のどちらか片方または両方を指定することができます。 もし URL のみを指定する場合、"bugs"フィールドの値は単純文字列で指定できます。

URL が指定されている場合、npm bugs コマンドで使われます。

パッケージ利用における許諾や制限が分かるよう、ライセンスを記載します。

BSD-2-Clause や MIT といった一般的なライセンスを用いる場合、 SPDXライセンス識別子 を指定します。

サンプル：

{
  "license": "BSD-3-Clause"
}

SPDXライセンス識別子は こちら を参照してください。 理想的には OSI 承認されたものを利用してください。

複数ライセンスを適用する場合、SPDXライセンス構文に従って記載してください。

サンプル：

{
  "license": "(ISC OR GPL-3.0)"
}

SPDXライセンス識別子を利用せず独自のライセンスを使う場合、以下のような文字列値を指定します。

{
  "license": "SEE LICENSE IN <filename>"
}

filename に指定されるファイルはパッケージのトップレベルに配置してください。

"author" は1人、 "contributors" は 複数人です。 人を表現するオブジェクトは "name" フィールドとオプションで "url" と "email" を持ちます。

サンプル：

{
  "name": "Barney Rubble",
  "email": "barney@rubble.com",
  "url": "http://barnyrubble.tumblr.com/"
}

これらを短くした単一文字列表現も利用できます。

サンプル：

"Barney Rubble <Barney@rubble.com> (http://barneyrubble.tumblr.com/)"

"email" と "url" のどちらもオプションです。

プロジェクトに含まれるファイルリストを指定します。 もしフォルダー名のリストを指定する場合、フォルダーにあるファイルが含まれます。 （ただし、他のルールは無視されます）

パッケージのルートディレクトリまたはサブディレクトリに ".npmignore"ファイル を配置することができます。 これは ".npmignore" はちょうど ".gitignore" のような動きをします。

以下のファイルは設定に関わらず常に含まれます。

• package.json
• README
• CHANGELOG
• LICENSE / LICENCE

以下のファイルは常に無視されます。

• .git
• CVS
• .svn
• .hg
• .lock-wscript
• .wafpickle-N
• *.swp
• .DS_Store
• ._*
• npm-debug.log

パッケージのエントリーポイントを指定します。 foo というパッケージを作成して、ユーザーがインストールし、require("foo") を実行すると、 mainモジュールで出力設定されたオブジェクトが返されます。

パッケージフォルダのルートからの相対パスで指定します。

多くのモジュールにおいてメインスクリプトを指定すると考えると分かりやすいです。

多くのパッケージにおいて PATH に実行可能なファイルをインストールしたいという場合があります。 npm では簡単に設定できます。

利用するには、コマンド名からローカルファイル名へのマッピング情報を package.json の binフィールドに設定します。 インストールするとき、グローバルインストールの場合シンボリックリンクを prefix/bin に、ローカルインストールの場合 ./node_modules/.bin/ に配置します。

例えば myapp を以下のように設定した場合、

"bin": {
  "myapp": "./cli.js"
}

myapp をインストールすると、 cli.js スクリプトへのシンボリックリンクを /usr/local/bin/myapp へ作成します。

もし単一の実行可能ファイルでパッケージ名と同じ名前の場合、単純な文字列で表記することができます。

サンプル（以下の2つは同じです）：

"bin": {
  "name": "my-program",
  "version": "1.2.5",
  "bin": "./path/to/program"
}

"bin": {
  "name": "my-program",
  "version": "1.2.5",
  "bin": {
    "my-program": "./path/to/program"
  }
}

man プログラム向けに単一ファイルかファイル名の配列を指定します。

単一ファイルを指定する場合、指定したファイル名に関わらず man <パッケージ名> で呼び出せます。

例えば以下のような設定をした場合、 ./man/doc.1 というファイルは man foo コマンドで呼び出されます。

{
  "name": "foo",
  "version": "1.2.3",
  "description": "A packaged foo fooer for fooing foos",
  "main": "foo.js",
  "man": "./man/doc.1"
}

ファイル名がパッケージ名で始まっていない場合、プレフィックスにパッケージ名が付きます。 例えば以下のような設定をした場合、man foo および man foo-bar が作られます。

{
  "name": "foo",
  "version": "1.2.3",
  "description": "A packaged foo fooer for fooing foos",
  "main": "foo.js",
  "man": ["./man/foo.1", "./man/bar.1"]
}

manファイルのファイル名は数値で終わっている必要があります。 オプションで、圧縮している場合は .gz サフィックスが付けられます。 数値はセクションを示しており、以下のような設定をした場合、 man foo および man 2 foo が作られます。

"doc"、"lib"、"man"といったディレクトリがどこにあるかを定義できます。

例えば以下のような設定を記述します。

{
   "lib": "src/lib",
   "bin": "local/binaries",
   "doc": "doc" 
} 

コードがどこにあるかを定義します。コード修正に参加したいと思った人にとって有用な情報になります。 GitHub上にリポジトリがあれば npm docs コマンドで参照できます。

"repository": {
  "type" : "git",
  "url" : "https://github.com/npm/npm.git"
}

"repository": {
  "type" : "svn",
  "url" : "https://v8.googlecode.com/svn/trunk/"
}

URLは一般に公開されたURLを使用します。 また、htmlページではなく機械が読み取れるURLを指定します。

GitHub、GitHub gist、Bitbucket、GitLabリポジトリを利用する場合、ショートハンドが利用できます。

"repository": "npm/npm"

"repository": "gist:11081aaa281"

"repository": "bitbucket:example/repo"

"repository": "gitlab:another/repo"

パッケージのライフサイクル中における様々なシーンで呼び出されるコマンドを定義します。 キーはライフサイクル中のイベント名で、値はコマンド実行されたときに実行するスクリプトを定義します。

以下は "install" および "uninstall" コマンドを定義するサンプルです。

"scripts" : {
  "install" : "scripts/install.js",
  "uninstall" : "scripts/uninstall.js"
}

config オブジェクトではパッケージスクリプトで利用する設定値を指定できます。 例えば以下のような設定を行った場合、

{
  "name" : "foo",
  "config" : {
    "port" : "8080"
  }
}

npm_package_config_port という環境変数が設定されます。 この値は npm config set foo:port 8001 のように実行することで上書きすることもできます。

dependencies は単純なオブジェクトでパッケージ名とバージョン範囲を指定します。 バージョン範囲は1つ以上のスペース区切り文字列を指定します。 dependencies には tarball や git の URL を指定することもできます。

テスト用の依存ファイルは指定しないでください。 以下の devDependencies を参照してください。

バージョン番号に関する詳細は semver を参照してください。

サンプルは以下のようになります。

"dependencies" : {
  "foo" : "1.0.0 - 2.9999.9999",
  "bar" : ">=1.0.2 <2.1.2",
  "baz" : ">1.0.2 <=2.3.4",
  "boo" : "2.0.1",
  "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0",
  "asd" : "http://asdf.com/asdf.tar.gz",
  "til" : "~1.2",
  "elf" : "~1.2.3",
  "two" : "2.x",
  "thr" : "3.3.x",
  "lat" : "latest",
  "dyl" : "file:../dyl"
}

URL

tarball への URL を指定します。 指定された tarball はインストール時にダウンロードされます。

Git URL

Git URL は以下のように指定します。

git://github.com/user/project.git#commit-ish
git+ssh://user@hostname:project.git#commit-ish
git+ssh://user@hostname/project.git#commit-ish
git+http://user@hostname/project/blah.git#commit-ish
git+https://user@hostname/project/blah.git#commit-ish

commit-ish には git checkout の引数で利用するタグ、sha、ブランチを指定できます。 デフォルトは master です。

GitHub URL

バージョン 1.1.65 以降では、"foo" : "user/foo-project" のように指定できます。 Git URL のように commit-ish サフィックスをふくめることもできます。

{
  "name": "foo",
  "version": "0.0.0",
  "dependencies": {
    "express": "visionmedia/express",
    "mocha": "visionmedia/mocha#4727d357ea"
  }
}

ローカルパス

バージョン 2.0.0 以降では、パッケージに含んでいるローカルディレクトリのパスを指定できます。 ローカルパスは npm install -S または npm install --save で保存できます。 保存する際は相対パスで package.json に保存されます。

{
  "name": "baz",
  "dependencies": {
    "bar": "file:../foo/bar"
  }
}

この機能は外部サーバーへアクセスしたくない、ローカルオフライン開発やテスト実施においてnpmインストールが必要な時に便利です。 ただし、パッケージを一般公開する際は使わないようにしてください。

公開されたパッケージを利用する際、テストフレームワークやドキュメントフレームワークといったものはダウンロードする必要がありません。 こうした場合、一番良いのはこれらを devDependencies に指定することです。

ここで指定したパッケージはパッケージルートで npm link または npm install を実行するとインストールされ、他のパラメータと同様に管理されます。 詳しくは npm-config を参照してください。

CoffeeScriptといったプラットフォーム固有でないビルドイベントは、devDependencies でパッケージ依存を指定して prepublish スクリプトを使うことで実現します。

サンプル：

{
  "name": "ethopia-waza",
  "description": "a delightfully fruity coffee varietal",
  "version": "1.2.3",
  "devDependencies": {
    "coffee-script": "~1.6.3"
  },
  "scripts": {
    "prepublish": "coffee -o lib/ -c src/waza.coffee"
  },
  "main": "lib/waza.js"
}

prepublishスクリプト は公開前に実行されます。 そのため、ユーザーはコンパイルを気にすることなく機能を利用することができます。 開発モード（例えば、ローカルで npm install を実行する場合）、このスクリプトはうまく動作するため、簡単にテストができます。

場合により、ホストツールやライブラリとの互換性のため、必ずしも必要ではないパッケージがあるかもしれません。 これは一般にプラグインと呼ばれるものです。 特に、ホストドキュメントによって期待されるまたは指定される、特定のインターフェースを公開しているかもしれません。

サンプル：

{
  "name": "tea-latte",
  "version": "1.3.5",
  "peerDependencies": {
    "tea": "2.x"
  }
}

あなたのパッケージ tea-latte をインストールすることができるのはホストパッケージである tea がバージョン 2.x の場合のみとすることができます。 npm install tea-latte は以下の依存グラフの場合だけ実行できます。

├── tea-latte@1.3.5
└── tea@2.2.0

注意： npm のバージョンが 1 または 2 の場合、peerDependencies で指定されたバージョンより高ければ自動的にインストールを行います。 次のバージョン (バージョン 3) ではこのようなことが起こらなくなり、代わりに警告が表示されるようになります。 npm 1 と 2 のこの動作は頻繁に混乱を起こし依存地獄に陥れていましたが、できるだけ避けられるようにデザインされます。

他のプラグインをインストールしようとしたとき依存エラーを起こすことがあります。 この原因は、あなたのプラグインが要求する依存バージョンがパッチバージョンまで指定してしまっているためです。

ホストコンパイルを考えたとき、ホストパッケージのメジャーバージョンの変更のみがあなたのプラグインを壊します。 ですから、もしあなたがすべてのホストパッケージをバージョン 1.x で動作させたいなら、 ^1.0 または 1.x を指定します。 もし 1.5.2 で出てきた機能に依存しているのであれば >=1.5.2 <2 を指定します。

パッケージ公開するときバンドルするパッケージの配列を指定します。

bundleDependencies の綴りでも動作します。

dependency を利用するがインストール時に失敗とさせたくない場合、 optionalDependencies を利用します。 これはパッケージ名とバージョンまたはURLのマップブジェクトで、dependencies に似ています。 違いはインストール時のエラーを発生させない点です。

インストールは行われるので、依存関係が欠損している部分をプログラムで処理s手あげる必要があります。 以下にサンプルコードを記載します。

try {
  var foo = require('foo')
  var fooVersion = require('foo/package.json').version
} catch (er) {
  foo = null
}
if ( notGoodFooVersion(fooVersion) ) {
  foo = null
}

// .. then later in your program ..

if (foo) {
  foo.doFooThings()
}

optionalDependencies の値は dependencies で上書きされます。

動作するnodeバージョンを指定することができます。

"engines" : {
  "node" : ">=0.10.3 <0.12"
}

dependencies と同様に特に指定しないまたは "*" を指定した場合、どのnodeバージョンでも動作します。 engines はどのバージョンで正しく動作するかを指定します。

engine-strict フラグが設定されていなければ、この値は警告を表示するのみの動作になります。

この機能は npm 3.0.0 で廃止されます。

npm 3.0.0 以降では engine-strict を指定するようにしてください。

どの OS で動作するかを指定します。

"os": [
  "darwin", "linux"
]

! を使用することでブラックリスト指定もできます。

"os": [
  "!win32"
]

ブラックリストとホワイトリストは両方使えます。

ある特定のCPUアーキテクチャで動作する場合、それを指定します。

"cpu": [
  "x64", "ia32"
]

ブラックリストも指定できます。

"cpu": [
  "!arm", "!mips"
]

あなたのパッケージがグローバルに利用されるコマンドラインアプリケーションである場合、この値を true にして ローカルインストールされた場合に警告表示するようにします。

"private" : true を設定すると、npm は該当パッケージの公開を拒否します。

これは間違ってプライベートリポジトリが公開されるのを防ぐために使います。 もしパッケージを特定のレジストリにのみ公開したい場合は publishConfig を設定して registry 設定を公開するときに上書きする設定を行ってください。

公開時に利用される設定値を指定します。 タグ、レジストリ、アクセス先を指定すると、 特定のパッケージに "latest" のタグ付けがされていない、 グローバルに公開されたレジストリを使う、 デフォルトでプライベートなモジュールを見ている、といったものの扱いで便利です。

あらゆる設定が上書き可能ですが、tag 、registry、 access が重要です。

上書き可能なオプションは npm-config を参照してください。