本ページは npm.org 提供文書を翻訳したものです。 原文は 本家参照 、誤謬・誤記の指摘は こちら からお願いします。 ×

package.json

npm package.json 取扱説明書

記述方法

このドキュメントを通じて、あなたの package.json に必要な全てを 学ぶことが出来ます。記述は JavaScript のオブジェクトリテラルではなく、 正しい JSON でなければなりません。

このドキュメントの多くの振る舞いは npm-config(7) に書かれている設定に影響を受けています。

name

package.json の中で最も大事な項目は "name"(名前) と "version"(バージョン) です。必須であり、パッケージはこれらなしで インストール出来ません。name と version をもってして、パッケージが 完全に一意となることが想定されています。よってパッケージ内容を変更するには version を変更しなければなりません。

name: パッケージの呼び名に関するつけ方のコツ:

パッケージ名はスコープの指定により接頭することができます(例: @myorg/mypackage)。 詳しくは npm-scope(7) を見てください。

version

package.json の中で最も大事な項目は "name" と "version" です。必須であり、パッケージはこれらなしで インストール出来ません。name と version をもってして、パッケージが 完全に一意となることが想定されています。よってパッケージ内容を変更するには version を変更しなければなりません。

version は npm と依存関係にあるnode-semver で解釈可能でなければなりません。 ( npm install semver であなた自身も利用可能です。)

version に関する数字と範囲の仕様は semver(7) を見て下さい。

description

説明を文字列で記述します。 npm search で表示されるので、人々があなたの作ったパッケージを見つけ、理解するのに役立ちます。

keywords

キーワードを文字列に配列で記述します。 npm search で表示されるので、人々があなたの作ったパッケージを見つけ、理解するのに役立ちます。

homepage

プロジェクトホームページがある場合、ここに記述します。

注意: これは "url" 項目とは 違います。 もし "url" をセットするとそれは外部に設置されたパッケージソースへのリダイレクトとなり、 想定外の動きを誘発します。

文字通り、予想外な動きをします。冗談ではありません。

bugs

プロジェクトの問題やバグ追跡を見る url とそれらの報告を行う email アドレスです。 これらはパッケージユーザーが問題に直面したときの助けとなるでしょう。

記述例:

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

どちらか一方のみ記述することも出来ます。 url のみ指定するときは オブジェクトではなく単純に文字列を "bugs" 項目に指定することも 出来ます。

url を指定したい場合には npm bugs コマンドが利用出来ます。

license

パッケージユーザーが使用許諾とあなたの指定している禁止事項を知る為にパッケージのライセンス情報を指定します。

最も単純な方法は BSD-3-Clause や MIT といった一般的なライセンスの 標準 SPDX ID を、このように指定することです:

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

SPDXは ライセンスID リスト を提供しています。 OSI の承認のあるものを利用するのが理想的です。

ライセンスファイルをパッケージの先頭に配置することもまた望ましいです。

people フィールド: author, contributor

"author" は一人だけを指定し、 "contributors" は複数の人を配列指定します。 一人の "人" の値として "name" フィールドと、任意で "url" と "email"をこのように指定します:

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

もしくは1つの文字列として省略しても書けます。この場合、npm が解釈してくれます:

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

email と url はどちらの書き方でも任意です。

npm はまた第一レベルに "maintainers" フィールドを、セットします。

files

"files" 項目はプロジェクトに含まれるファイルの配列です。 フォルダ名を指定した場合はフォルダの中のファイルも含まれます。 （他の設定により、そのファイルが無視されない場合です。）

".npmignore" というファイルをパッケージのルートレベルに 設置することが出来ます。指定されたファイルは "files" の配列で指定されていたとしても、 対象から除外されます。".npmignore" ファイルは ".gitignore" ファイルとちょうど同じです。

main

"main" 項目はパッケージの中で最初に呼ばれるモジュールのIDです。 つまりパッケージに foo と名前をつけ、それをユーザーがインストールし、 require("foo") を実行した時に "main" で指定したモジュールの exports オブジェクトが 返されます。

パッケージルートからの相対パスを指定しなければなりません。

多くのモジュールにとってメインスクリプトを持つことは有用でありますが しばしばそうでないかもしれません。

bin

多くのパッケージは１つ以上の、PATH に設定したい実行可能なファイルを持ちます。 npm ではとっても簡単に実現出来ます。（実際この機能はインストールで "npm" を実行可能とする上でも 用いられています。）

コマンド名のマップを package.json の bin 項目に記述して利用出来ます。インストール時に npm はコマンドを呼び出すためのシンボリックリンクを グローバルインストール時 (注釈： -g オプションをつけてのインストール) は prefix/bin に、ローカルインストールでは ./node_modules/.bin/ に作成します。

例えば npm ではこう指定されています:

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

なので、npm をインストールしたとき、シンボリックリンクが cli.js に向けて /usr/local/bin/npm に作成されます。

もし単体実行モジュールで、それがパッケージ名(name)と同じであるのなら、 その場合は次のように文字列で記述されます:

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

以下と同じ意味です:

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

man

man プログラムが見るひとつのファイル名もしくは複数のファイル名の配列を指定します。

もしひとつのプログラムだけが指定された場合は、ファイル名なしで man <pkgname> の結果として得ることができます。 

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

上のように指定することで ./man/doc.1 は man foo のターゲットファイルとなります。

もしファイル名がパッケージ名で始まらない場合は、前置されます:

{ "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 foo と man foo-bar を実行したい場合は上のように作成します。

man ファイルは数字で終わる必要があり、圧縮している場合は .gz の拡張子を付けます。数字は man の段落(section)番号となります。 

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

man foo と man 2 foo が作成されます。

directories

共通JS Packages 規約に則って directories オブジェクトを記述して、いくつかのパッケージ構成を示すことが出来ます。 npm package.json をみれば doc、lib や man ディレクトリ構成を確認することが出来ます。

将来的にこれらの情報はより創造的な目的に利用します。

directories.lib

小分けにされたライブラリがどこにあるか示します。 lib フォルダに特別なことは行いませんが、メタデータとして有用です。

directories.bin

bin フォルダを設置した場合、フォルダ内の全てのファイルが bin パスの下に配置されます。

もし bin パスを記述している場合は、影響がありません。

directories.man

man ページの全てを入れます。フォルダ内を走査して、"man" 配列がつくられます。

directories.doc

markdown ファイルを入れます。これらは結果的に美しく表示されるでしょう、多分、いつの日か。

directories.example

利用例のスクリプトファイルを入れます。将来的に、賢明に外部表示されるでしょう。

repository

ソースコードが管理されている場所を指定します。ソースコードに関与したい人々に とってそれは助けとなるでしょう。もし github 上の git リポジトリであれば npm docs コマンドでそのパッケージが発見可能になります。

推奨記述:

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

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

URL は変更なく VCS プログラムで操作可能な、 （おそらく読み取り専用であっても）公開されていなければなりません。 これはプロジェクトのページではありません、コンピュータが解釈するためのものです。

scripts

"script" はパッケージ動作上、様々なタイミングで実行される script コマンド のプロパティです。キーがイベント、そして値がコマンドです。

npm-scripts(7) に記述方法の詳細を記載しています。

config

"config" オブジェクトはパッケージのバージョンに依らず指定する、プログラムを動かす時の 設定情報です。例えば、パッケージに以下のような値が設定されているとします:

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

"start" コマンドを実行したとき npm_package_config_port が参照されます。以下のコマンドでユーザーはこれを上書きすることができます。 npm config set foo:port 8001

npm-config(7) 及び npm-scripts(7) で詳細を記述しています。

dependencies

バージョン範囲を含むパッケージ名で依存性を簡単なオブジェクトで記述出来ます。 バージョン範囲はスペースで仕切られた１つ以上の演算子で記述します。 依存性は tarboll や git URL でも指定出来ます。

テストハーネス(訳注：テストスクリプトを自動実行するようなもの)やトランスパイラー(訳注：gruntjsのようにリリースモジュールを作成するためのモジュール)を dependencies オブジェクトに 用いないで下さい。 devDependencies を参照下さい。

semver(7) にバージョン範囲の指定方法 の詳細を記述しています。

有効な記述例:

        { "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 を許容するのであればどのtagでもshaでもブランチでも構いません。 既定は master です。

GitHub URL参照

npm バージョン 1.1.65 から、GitHub url を "foo": "user/foo-project". のように指定出来ます:

         { "name": "foo",
          "version": "0.0.0",
          "dependencies": { "express":
          "visionmedia/express" } }

Local Paths

2.0.0 から パッケージを含む ローカルディレクトリを提供 することができます。Local paths は npm install --save を使って 保存でき、任意の形式で記述できます:

../foo/bar
      ~/foo/bar
      ./foo/bar
      /foo/bar

この場合、相対パスは標準化して package.json に書き込まれます。例えば:

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

この機能はローカルでのオフライン環境下の開発 と、外部サーバーへ接続して欲しくない npm install を必要とする テスト開発を手助けしますが、公開リポジトリへ publish するときには 使用すべきでありません。

devDependencies

パッケージモジュールを利用する人にとって、 パッケージのテストやドキュメンテーションに利用している 外部のフレームワークは恐らくダウンロードも実行もしたくないでしょう。

こういった場合、 devDependencies オブジェクトにこれらを記載することが一番良い方法です。

これらのモジュールは npm link もしくは npm install をパッケージのルートポジションで実行することで取得、実行されます。 そして他の npm の設定項目と同じように管理できます。 npm-config(7) で補足説明を確認出来ます。

CoffeeScriptのようなJavaScriptへコンパイルする プラットフォーム特有の 前段階 があるとき、 devDependency の記述が必要になります。

例:

         { "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" }

この 前段階 のスクリプトは公開前に実行可能であるため、パッケージユーザーは コンパイルすることなく、機能を享受することができます。（ローカルでの npm install をした場合の）開発者モードではこれらの スクリプトを同様に実行するため、テストを簡潔に行うことが可能です。

peerDependencies

時に require とする必要がなくても、 提供ツールや提供ライブラリと互換性がパッケージにあることを 表現したくなるケースもあります。 この項目は plugin として参照されます。とりわけ、 特定のインターフェースをパッケージの提供が、パッケージから 期待され、記述されているる場合です。

例:

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

この場合 tea-latte は提供パッケージ tea が2番目の主要パッケージとして ともに インストールされることを保証します。 提供パッケージは必要な場合に自動でインストールされます。 npm install tea-latte は以下のような依存性グラフを出力するでしょう:


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

要件が競合するパッケージをインストールしようとすると エラーが起こります。この理由から、plugin 条件はできるだけ広くとり、 特定のパッチバージョンを指定しないようにしてください。

semver で提供するとすると、主要バージョンを変えることで プラグインは動かなくなってしまいます。なので、提供されるすべての 1.x バージョンで 動くことを表現するす場合、"^1.0" または "1.x" と記述します。もし 1.5.2 で提供されるものと依存性を持たせるならば、 ">= 1.5.2 < 2" と記述するのが良いでしょう。

bundledDependencies

公開(publish)時にバンドルするパッケージの配列。

これを "bundleDependencies" と記述すればより賢明でしょう。

optionalDependencies

利用可能にはしたいモジュールではあるが、見つからない場合やインストール失敗 の場合にもパッケージの npm を実行させつづけたい場合は、 optionalDependencies に記述します。ここにはバージョンを含めたパッケージ名若しくは urlを dependencies と同様に記載します。違いはビルドが失敗してもインストールは止まらないことです。

以下のように、依存性モジュールの欠損の場合の対応がある場合などに も対応している場合に用います:

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 に名前の同じものがある場合、上書きされます。 ですから、一方にのみ記載されていることが最善です。

engines

動作可能な node のバージョンを指定できます:

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

"dependencies" と同じく、バージョンを指定しない場合（もしくは "*" をバージョンに指定した場合）は、どの node バージョンでもインストール可能と なります。

"engines" 項目を指定すると、 npm はリスト内のいずれかに該当する "node" を必要とします。 "engines" が省略されている場合、node 上では動くものと解釈します。

"engines" 項目で npm のバージョンを指定することもできます:

        { "engines" : { "npm" : "~1.0.20" } }

engine-strict 設定フラグを有効にしない場合、この項目はアドバイスに留まります。

engineStrict

パッケージのモジュールが engines 項目で指定したバージョンの Node および npm 以外では 全くもって動作しない ことがわかっている 場合、 "engineStrict": true 項目を package.json に設定します。これはユーザーの engine-strict 設定を上書きします。

本当に、全くもって動かない場合以外はこの設定を行わないで下さい。 あまり大袈裟に拒否すると、ついうっかり動作を限定してしまったり、 ユーザーの新しい node へのバージョンアップを妨げてしまうことがあります。 設定には十分に考慮してください。もし乱用が見受けられれば、将来的に npm の機能として取り除きます。

os

どのオペレーティングシステムで動作するか指定することが出来ます:

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

ホワイトリスト（訳注：許可OSリスト）を指定する代わりに、 '!' を前置するだけで、ブラックリスト（訳注：拒否OSリスト）を指定することもできます:

"os" : [ "!win32" ]

オペレーティングシステムの文字列は process.platform で定められたものです。

状況的にはあまりないと思いますが、 ホワイトリストとブラックリストの両方を指定することもできます。

cpu

もし限られた cpu アーキテクチャでしかパッケージモジュールが動かない場合は、 それを指定することが出来ます。

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

os 項目と同じく、ブラックリストも指定出来ます。 

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

cpu アーキテクチャの文字列は process.arch で定められたものです。

preferGlobal

パッケージがグローバルインストール（訳注：-g オプションをつけたインストール） を行うべきであれば、この値を true にし、ローカルインストールにおいて警告を出すことが出来ます。

これはローカルインストールを完全に妨げる者ではありませんが、 パッケージが想定と異なる動作をした場合に、混乱を避ける助けとなります。

private

"private": true を package.json に設定しておくと、publish コマンドを拒否します。

このフラグはプライベートなリポジトリをうっかり publish してしまう ことを防止します。もし（内部的なレジストリなど）特定のレジストリのみにリリースするような環境を 望むのであれば 後述している publishConfig を利用して、 publish 時に registry 設定を上書きすることが出来ます。

publishConfig

publish 時に利用される設定値です。パッケージが"latest"タグ 付けされたり、一般公開レジストリに publish されてしまうことがないよう、 タグまたはレジストリを設定しておくのに便利です。

設定項目は上書きされますが、 "tag" と "registry" の項目は publish 時に大変重要なものです。

上書き可能な config オプションは npm-config(7) で確認出来ます。

規定値

npm はパッケージ内容に合わせて規定値を設定します。

参考

© Liberty Technology リンクフリーです。再構成・再配布については こちら からお問い合わせ下さい。