(
この記事は package.json - Specifics of npm's package.json handling をベースに作成しています。
package.json
を作成する際、その 書き方 の 参考 になればと思います。
)
このドキュメントは pakage.json
に何を書くべきか について記載しています。
package.json
は単に JavaScript オブジェクトリテラルであるだけでなく JSON でなければなりません。
このドキュメントに記載した動作の多くは npm-config に記載された設定の影響を受けます。
{ "name": "blue-leaf", "description": "Physics-like animations for pretty particles", "main": [ "js/motion.js", "sass/motion.scss" ], "dependencies": { "get-size": "~1.2.2", "eventEmitter": "~4.2.11" }, "devDependencies": { "qunit": "~1.16.0" }, "moduleType": [ "amd", "globals", "node" ], "keywords": [ "motion", "physics", "particles" ], "authors": [ "Betty Beta <bbeta@example.com>" ], "license": "MIT", "ignore": [ "**/.*", "node_modules", "bower_components", "test", "tests" ], "homepage": "http://betty.github.io/blue-leaf/index.html", "repository": { "type": "git", "url": "git://github.com/betty/blue-leaf.git" }, "resolutions": { "angular": "1.3.0-beta.16" }, "private": true }
プロパティ名 | 型 | 説明 | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
name | string | 必須 package.json にとって name と version はもっとも重要なフィールドです。 これらは必須項目で、これらが指定されていないと パッケージ をインストールできません。 name と version の組み合わせでパッケージを一意に特定します。 パッケージの変更は version の変更も伴うべきものです。 ルール:
ヒント:
|
||||||||||||||||||||||||||||||||||||
version | string | 必須 version は npm の依存として含まれている node-semver で構文解析可能でなければなりません。 バージョン番号に関する詳細は semver を参照してください。 |
||||||||||||||||||||||||||||||||||||
description | string | 説明を記載します。
作成するパッケージを、npm search でリストする際、探しやすくします。 |
||||||||||||||||||||||||||||||||||||
keywords | string[] | キーワードを文字配列で記載します。
作成するパッケージを、npm search でリストする際、探しやすくします。 |
||||||||||||||||||||||||||||||||||||
homepage | string | プロジェクトホームページへのURL。 注意: "homepage" は "url"とは異なりませ宇。 もし "url" フィールドを設定する場合、レジストリはパッケージが別の場所に移されたのでリダイレクトしようとします。 |
||||||||||||||||||||||||||||||||||||
bugs | object | バグトラッカーへの URL または / かつ バグ連絡先となる メールアドレス。 これらの値はパッケージ利用者がバグに遭遇したときに役立ちます。 サンプル: { "url": "https://github.com/owner/project/issues", "email": "project@hostname.com" } "url" と "email" のどちらか片方または両方を指定することができます。 もし URL のみを指定する場合、"bugs"フィールドの値は単純文字列で指定できます。 URL が指定されている場合、 |
||||||||||||||||||||||||||||||||||||
license | string | パッケージ利用における許諾や制限が分かるよう、ライセンスを記載します。 BSD-2-Clause や MIT といった一般的なライセンスを用いる場合、 SPDXライセンス識別子 を指定します。 サンプル: { "license": "BSD-3-Clause" } SPDXライセンス識別子は こちら を参照してください。 理想的には OSI 承認されたものを利用してください。 複数ライセンスを適用する場合、SPDXライセンス構文に従って記載してください。 サンプル: { "license": "(ISC OR GPL-3.0)" } SPDXライセンス識別子を利用せず独自のライセンスを使う場合、以下のような文字列値を指定します。 { "license": "SEE LICENSE IN <filename>" }
|
||||||||||||||||||||||||||||||||||||
author / conributors | string / object / string[] / object[] | "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" のどちらもオプションです。 |
||||||||||||||||||||||||||||||||||||
files | string[] | プロジェクトに含まれるファイルリストを指定します。 もしフォルダー名のリストを指定する場合、フォルダーにあるファイルが含まれます。 (ただし、他のルールは無視されます) パッケージのルートディレクトリまたはサブディレクトリに ".npmignore"ファイル を配置することができます。 これは ".npmignore" はちょうど ".gitignore" のような動きをします。 以下のファイルは設定に関わらず常に含まれます。
以下のファイルは常に無視されます。
|
||||||||||||||||||||||||||||||||||||
main | string | パッケージのエントリーポイントを指定します。
パッケージフォルダのルートからの相対パスで指定します。 多くのモジュールにおいてメインスクリプトを指定すると考えると分かりやすいです。 |
||||||||||||||||||||||||||||||||||||
bin | object | 多くのパッケージにおいて 利用するには、コマンド名からローカルファイル名へのマッピング情報を package.json の binフィールドに設定します。
インストールするとき、グローバルインストールの場合シンボリックリンクを 例えば myapp を以下のように設定した場合、 "bin": { "myapp": "./cli.js" } 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 | string / string[] |
単一ファイルを指定する場合、指定したファイル名に関わらず 例えば以下のような設定をした場合、 { "name": "foo", "version": "1.2.3", "description": "A packaged foo fooer for fooing foos", "main": "foo.js", "man": "./man/doc.1" } ファイル名がパッケージ名で始まっていない場合、プレフィックスにパッケージ名が付きます。
例えば以下のような設定をした場合、 { "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ファイルのファイル名は数値で終わっている必要があります。
オプションで、圧縮している場合は |
||||||||||||||||||||||||||||||||||||
directories | object | "doc"、"lib"、"man"といったディレクトリがどこにあるかを定義できます。
例えば以下のような設定を記述します。 { "lib": "src/lib", "bin": "local/binaries", "doc": "doc" } |
||||||||||||||||||||||||||||||||||||
repository | object / string | コードがどこにあるかを定義します。コード修正に参加したいと思った人にとって有用な情報になります。
GitHub上にリポジトリがあれば "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" |
||||||||||||||||||||||||||||||||||||
scripts | object | パッケージのライフサイクル中における様々なシーンで呼び出されるコマンドを定義します。 キーはライフサイクル中のイベント名で、値はコマンド実行されたときに実行するスクリプトを定義します。 以下は "install" および "uninstall" コマンドを定義するサンプルです。 "scripts" : { "install" : "scripts/install.js", "uninstall" : "scripts/uninstall.js" } |
||||||||||||||||||||||||||||||||||||
config | object | config オブジェクトではパッケージスクリプトで利用する設定値を指定できます。 例えば以下のような設定を行った場合、 { "name" : "foo", "config" : { "port" : "8080" } }
|
||||||||||||||||||||||||||||||||||||
dependencies | object |
テスト用の依存ファイルは指定しないでください。
以下の バージョン番号に関する詳細は 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" } tarball への URL を指定します。 指定された tarball はインストール時にダウンロードされます。 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
バージョン 1.1.65 以降では、 { "name": "foo", "version": "0.0.0", "dependencies": { "express": "visionmedia/express", "mocha": "visionmedia/mocha#4727d357ea" } } バージョン 2.0.0 以降では、パッケージに含んでいるローカルディレクトリのパスを指定できます。
ローカルパスは { "name": "baz", "dependencies": { "bar": "file:../foo/bar" } } この機能は外部サーバーへアクセスしたくない、ローカルオフライン開発やテスト実施においてnpmインストールが必要な時に便利です。 ただし、パッケージを一般公開する際は使わないようにしてください。 |
||||||||||||||||||||||||||||||||||||
devDependencies | object | 公開されたパッケージを利用する際、テストフレームワークやドキュメントフレームワークといったものはダウンロードする必要がありません。
こうした場合、一番良いのはこれらを ここで指定したパッケージはパッケージルートで CoffeeScriptといったプラットフォーム固有でないビルドイベントは、 サンプル: { "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" }
|
||||||||||||||||||||||||||||||||||||
peerDependencies | object | 場合により、ホストツールやライブラリとの互換性のため、必ずしも必要ではないパッケージがあるかもしれません。 これは一般にプラグインと呼ばれるものです。 特に、ホストドキュメントによって期待されるまたは指定される、特定のインターフェースを公開しているかもしれません。 サンプル: { "name": "tea-latte", "version": "1.3.5", "peerDependencies": { "tea": "2.x" } } あなたのパッケージ tea-latte をインストールすることができるのはホストパッケージである tea がバージョン 2.x の場合のみとすることができます。
├── tea-latte@1.3.5 └── tea@2.2.0 注意: npm のバージョンが 1 または 2 の場合、peerDependencies で指定されたバージョンより高ければ自動的にインストールを行います。 次のバージョン (バージョン 3) ではこのようなことが起こらなくなり、代わりに警告が表示されるようになります。 npm 1 と 2 のこの動作は頻繁に混乱を起こし依存地獄に陥れていましたが、できるだけ避けられるようにデザインされます。 他のプラグインをインストールしようとしたとき依存エラーを起こすことがあります。 この原因は、あなたのプラグインが要求する依存バージョンがパッチバージョンまで指定してしまっているためです。 ホストコンパイルを考えたとき、ホストパッケージのメジャーバージョンの変更のみがあなたのプラグインを壊します。
ですから、もしあなたがすべてのホストパッケージをバージョン 1.x で動作させたいなら、 |
||||||||||||||||||||||||||||||||||||
bundledDependencies | string[] | パッケージ公開するときバンドルするパッケージの配列を指定します。
|
||||||||||||||||||||||||||||||||||||
optionalDepencencies | object |
インストールは行われるので、依存関係が欠損している部分をプログラムで処理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() }
|
||||||||||||||||||||||||||||||||||||
engines | object | 動作するnodeバージョンを指定することができます。 "engines" : { "node" : ">=0.10.3 <0.12" }
|
||||||||||||||||||||||||||||||||||||
engineStrict | boolean | この機能は npm 3.0.0 で廃止されます。 npm 3.0.0 以降では |
||||||||||||||||||||||||||||||||||||
os | string[] | どの OS で動作するかを指定します。 "os": [ "darwin", "linux" ]
"os": [ "!win32" ] ブラックリストとホワイトリストは両方使えます。 |
||||||||||||||||||||||||||||||||||||
cpu | string[] | ある特定のCPUアーキテクチャで動作する場合、それを指定します。 "cpu": [ "x64", "ia32" ] ブラックリストも指定できます。 "cpu": [ "!arm", "!mips" ] |
||||||||||||||||||||||||||||||||||||
preferGlobal | boolean | あなたのパッケージがグローバルに利用されるコマンドラインアプリケーションである場合、この値を |
||||||||||||||||||||||||||||||||||||
private | boolean |
これは間違ってプライベートリポジトリが公開されるのを防ぐために使います。
もしパッケージを特定のレジストリにのみ公開したい場合は |
||||||||||||||||||||||||||||||||||||
publishConfig | 公開時に利用される設定値を指定します。 タグ、レジストリ、アクセス先を指定すると、 特定のパッケージに "latest" のタグ付けがされていない、 グローバルに公開されたレジストリを使う、 デフォルトでプライベートなモジュールを見ている、といったものの扱いで便利です。 あらゆる設定が上書き可能ですが、 上書き可能なオプションは npm-config を参照してください。 |
参考記事
最後に… このブログに興味を持っていただけた方は、 ぜひ 「Facebookページ に いいね!」または 「Twitter の フォロー」 お願いします!!