JavaScript

package.jsonの中身を理解する

More than 1 year has passed since last update.

きっかけ

2017/3にnpmモジュールを公開した時に、そのモジュールのpackage.jsonを編集する必要が生じて、今までなんとなくしか理解してなかった各プロパティの意味を調べた。

全てのプロパティを網羅しているわけではない。随時更新していく。

name

モジュールの名前。必須項目。
ソース内でimportやrequire()でモジュール読み込みで利用される。npmモジュールはnameversionで一意となることが想定されているので、他のライブラリと名前が重複してはいけない。

{ "name": "react-native-card-media" }

version

モジュールのバージョン。必須項目。
npmモジュールはnameversionで一意となることが想定されている。バージョンアップのnpm公開するときは、バージョン番号の更新を忘れないように。

{ "version": "0.0.5" }

private

このプロパティがtrueになっていると、モジュールの公開ができない。公開しないプロジェクトは誤って公開しないようにtrueにしておく。

{ "private" : true }

description

モジュールの説明。
npm searchで表示されるので、人々があなたの作ったパッケージを見つけ、理解するのに役に立つ。

{ "description": "Card Media component for React Native. Also supports multiple image layout." }

main

モジュールの中で最初に呼ばれるスクリプトファイルを指定。
例えばモジュールにfooと名前をつけ、それをユーザーがインストールし、require("foo")を実行した時にmainで指定したモジュールのexportsオブジェクトが返される。
パッケージルートからの相対パスを指定しなければいけない。

{ "main": "index.js" }

scripts

任意のshell scriptを実行するエイリアスコマンドを定義できる。

{
  "scripts": {
    "test": "eslint *.js ./components/*.js ./example/*/*.js",
    "start":      "node app.js",
    "production": "NODE_ENV=production node app.js"
  }
}

キーはnpm testnpm startのようにエイリアスとして利用できる名前となり、値にはshell scriptをワンラインで指定する。

ただし、teststartなどの予約語以外をエイリアスコマンドとして、登録した場合はnpm run productionと実行する。

ワンラインのshell scriptを記述する際はdependenciesdevDependenciesに入っているモジュールの bin は、自動的に PATH に入る。

{
  "devDependencies": {
    "eslint": "^3.18.0"
  }
}

と、していれば

{
  "scripts": {
    "test": "node_modules/.bin/eslint *.js"
  }
}

ではなく

{
  "scripts": {
    "test": "eslint *.js"
  }
}

のように書ける。

scriptsは、もっとたくさんの機能があるみたいなので、今後追記していきたい。

repository

ソースコードが管理されている場所を指定する。

{
  "repository": {
    "type": "git",
    "url": "git+ssh://git@github.com/dondoko-susumu/react-native-card-media.git"
  }
}

author

author は一人だけを指定し、 contributors は複数の人を配列指定する。

このような省略形で書くのが一般的みたいだ。

{ "author": "Ken Kubota <kkbt2003@gmail> (https://github.com/dondoko-susumu/)" }

license

ライセンス情報。

{ "license" : "MIT" }

bugs

プロジェクトの問題やバグ追跡を見る url とそれらの報告を行う email アドレス。
GitHubであればIssueのURLを載せるのが一般的なようだ。

{
  "bugs": {
    "url": "https://github.com/dondoko-susumu/react-native-card-media/issues",
    "email" : "project@hostname.com"
  }
}

homepage

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

{
  "homepage": "https://github.com/dondoko-susumu/react-native-card-media#readme"
}

dependencies

依存するモジュールとバージョンを記述する。
package.jsonが置かれているディレクトリでnpm installすると、dependenciesと(devDependencies)に記述されたモジュールがnode_moduleディレクトリにインストールされる。

インストールされたモジュールの中にも依存しているモジュールがあれば、それもインストールされる。数珠つなぎのようにdependenciesに記載された依存関係にあるモジュールがインストールされていく。

テストスクリプトを自動実行するようなものやトランスパイラー(リリースモジュールをビルどするためのモジュール)をdependenciesに書いてはいけない。そういうものは後述するdevDependenciesに記述する。

--saveオプション

$ npm install --save co

--saveオプションを付けると、package.jsonに勝手に次のように登録される。

{
  "dependencies": {
    "co": "^4.6.0"
  }
}

バージョンの記法

^ (Caret Ranges)

--saveオプションで自動で登録されるバージョン指定(^(カレット)と呼ぶらしい)

^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

devDependencies

npmに公開するモジュールを開発するときに必要なものを定義する。

devDependenciesに記載されたものは、自分自身が別プロジェクトの外部モジュールとしてnpm installされる場合にはインストールされない。

対して、プロジェクトをGitでクローンしてnpm installした場合は、インストールされる。開発時のみに必要なライブラリで、実行時には役に立たないので、含める必要がない。

テストスクリプト、コンパイラ、タスクランナーなど モジュールとして読み込む際はいらないもの を定義していく。

ちなみに、エンドユーザとしてnpm installするとdependenciesdevDependenciesは両方ともインストールされる。

jest

package.jsonのトップレベルのjestキーでjestの設定を書くことができる。

設定にpresetを指定

presetにはjest-preset.jsonをトップレベルでexportsしているnpmモジュールを指定する。

{
  "jest": {
    "preset": "react-native"
  }
}

参考

公式 npm
公式 semver
npm package.json 取扱説明書
npm-scriptsについて
ちゃんと使い分けてる? dependenciesいろいろ。
3分でできるnpmモジュール
jest configuration