package.json

必須項目

package.json の2つの重要なフィールドに、nameversion があります。これらが無いと、パッケージをインストールすることは出来ません。 nameversionのフィールドは、一意な ID を作成するために併せて使用されます。

name

{
  "name": "my-awesome-package"
}

パッケージの名前を指定します。コマンドラインの引数としてURLの取得に使用され、また node_modules 内のディレクトリ名としても使用されます。

yarn add [name]
node_modules/[name]


https://registry.npmjs.org/[name]/-/[name]-[version].tgz

ルール

  • 214文字以下であること(スコープ付きパッケージの @scope/ を含む)
  • ドット(.) またはアンダースコア (_) から始めないこと
  • 名前に大文字を使用しないこと
  • URL セーフな文字のみ使用すること

Tips

  • Node.jsのコアモジュールと同じ名前は使用しないでください。
  • 名前にjsまたはnodeを入れないでください。
  • 短くて記述的な名付けを心がけてください。どのようなものか名前から理解できるようにしたいでしょうが、これはrequire()の呼び出しにも使用されます。
  • レジストリに同じ名前のものが無いことを確認してください。

バージョン

{
  "version": "1.0.0"
}

パッケージの現在のバージョンを指定します。

情報

description

{
  "description": "My short description of my awesome package"
}

description はパッケージの目的を人々が理解しやすくするための単なる文字列です。これはパッケージマネージャーで検索される際にも使用されます。

keywords

{
  "keywords": ["short", "relevant", "keywords", "for", "searching"]
}

keywords は、パッケージマネージャーによる検索を便利にするための文字列の配列です。

license

{
  "license": "MIT",
  "license": "(MIT or GPL-3.0)",
  "license": "SEE LICENSE IN LICENSE_FILENAME.txt",
  "license": "UNLICENSED"
}

全てのパッケージはライセンスを指定するべきです。そうすることでユーザーはどのように使用してよいのか、そしてあなたが定めた制限を知ることができます。

特別な理由がない限り、オープンソース ( OSI-approved) ライセンスを使用することをお勧めします。 もし仕事の一環としてパッケージをビルドしたのであれば、ライセンスを決定する前にあなたの会社に確認するのが良いでしょう。

次のいずれかでなければなりません:

  • 標準ライセンスを使用する場合には、有効な SPDX ライセンス識別子
  • 複数の標準ライセンスを使用する場合は、有効な SPDX 式構文 2.0 式
  • 非標準のライセンスを使用する場合は、パッケージの最上層の <filename> を指す SEE LICENSE IN <filename> 文字列
  • いかなる条件でも他者に非公開でプライベートなパッケージとし、使用する権利を付与したくない場合は、UNLICENSED の文字列

リンク

ドキュメント、issue の場所、パッケージのコードが実際に置かれている場所など様々なリンクを指定します。

homepage

{
  "homepage": "https://your-package.org"
}

homepage にはあなたのパッケージを紹介するページ、またはドキュメントのページを指定します。

bugs

{
  "bugs": "https://github.com/user/repo/issues"
}

プロジェクトの issueトラッカーの URL を指定します。これはメールアドレスのようなものを指定することも可能です。パッケージの問題をどこに報告すればよいのかをユーザーに伝えます。

repository

{
  "repository": { "type": "git", "url": "https://github.com/user/repo.git" },
  "repository": "github:user/repo",
  "repository": "gitlab:user/repo",
  "repository": "bitbucket:user/repo",
  "repository": "gist:a1b2c3d4e5f"
}

実際のパッケージのコードが置かれているリポジトリの場所を指定します。

メンテナー

あなたのプロジェクトをメンテナンスする人々です。

author

{
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "url": "http://your-website.com"
  },
  "author": "Your Name <you@example.com> (http://your-website.com)"
}

パッケージの著者の情報です。指定できる著者は1人だけです。

contributors

{
  "contributors": [
    { "name": "Your Friend", "email": "friend@example.com", "url": "http://friends-website.com" }
    { "name": "Other Friend", "email": "other@example.com", "url": "http://other-website.com" }
  ],
  "contributors": [
    "Your Friend <friend@example.com> (http://friends-website.com)",
    "Other Friend <other@example.com> (http://other-website.com)"
  ]
}

あなたのパッケージへのコントリビュータです。コントリビュータは配列で指定されます。

ファイル

プロジェクトの主となるエントリーポイントと共に、プロジェクトに含めるファイルを指定することが可能です。

files

{
  "files": ["filename.js", "directory/", "glob/*.{js,json}"]
}

プロジェクトに含まれるファイルを指定します。単一のファイル、ディレクトリ、またはワイルドカードを使用した特定の条件に一致するファイルを指定することが可能です。

main

{
  "main": "filename.js"
}

プロジェクトを機能させるための、主要なエントリーポイントを指定します。

bin

{
  "bin": "bin.js",
  "bin": {
    "command-name": "bin/command-name.js",
    "other-command": "bin/other-command"
  }
}

インストールされたプロジェクトに含まれる実行可能なファイルを指定します。

man

{
  "man": "./man/doc.1",
  "man": ["./man/doc.1", "./man/doc.2"]
}

プロジェクトが関連するman(マニュアル)ページを持つ場合は、ここに指定します。

directories

{
  "directories": {
    "lib": "path/to/lib/",
    "bin": "path/to/bin/",
    "man": "path/to/man/",
    "doc": "path/to/doc/",
    "example": "path/to/example/"
  }
}

パッケージのインストール時に、バイナリファイル、man ページ、ドキュメント、サンプル等が配置される正確な場所を指定します。

タスク

パッケージには、実行可能なスクリプトや、その他の設定を含めることが可能です。

scripts

{
  "scripts": {
    "build-project": "node build-project.js"
  }
}

scripts は単純なビルド処理や開発ツールなど、パッケージに関係するタスクを自動化するための優れた方法です。 "scripts" フィールドを使用すると、yarn run <script> で実行される様々なスクリプトを定義することができます。 例えば、上記の build-projectyarn run build-project によって実行され、node build-project.js の処理を実行します。

特定のスクリプト名は、特別扱いされます。 preinstall スクリプトを定義した場合は、パッケージがインストールされる直前に yarn によってこのスクリプトが呼び出されます。 互換性を保つために、installpostinstallprepublish のスクリプトがパッケージのインストール完了後に呼び出されます。

start スクリプトのデフォルト値は、node server.js になります。

config

{
  "config": {
    "port": "8080"
  }
}

スクリプト内で使用されるオプションやパラメーターを設定します。

依存関係

あなたのパッケージはほぼ間違いなく他のパッケージに依存するでしょう。 これらの依存関係を package.json ファイルに指定することができます。

dependencies

{
  "dependencies": {
    "package-1": "^3.1.4"
  }
}

開発環境と本環境の両方でパッケージに必要とされる依存関係です。

正確なバージョン、最低限のバージョン(例: >=)、バージョンの範囲(例: >= ... <)を指定することが可能です。

devDependencies

{
  "devDependencies": {
    "package-2": "^0.4.2"
  }
}

開発環境でのみ必要とされるパッケージで、本環境ではインストールされないパッケージです。

peerDependencies

{
  "peerDependencies": {
    "package-3": "^2.7.18"
  }
}

あなたのパッケージと他のパッケージのバージョンとの互換性を指定を可能にします。

optionalDependencies

{
  "optionalDependencies": {
    "package-5": "^1.6.1"
  }
}

あなたのパッケージと一緒に使用することができますが、必須ではないパッケージです。これらのパッケージが見つからなくても、インストールは続行されます。

bundledDependencies

{
  "bundledDependencies": ["package-4"]
}

あなたのパッケージが公開される際に一緒にバンドルされるパッケージを、パッケージ名の配列で指定します。

flat

{
  "flat": true
}

あなたのパッケージが与えられた依存関係の1つのバージョンしか許可しない場合、そしてコマンドラインの yarn install --flat と同じ挙動を強制させたい場合に、true を設定します。

もし、あなたの package.json"flat": true を含んでいて、他のパッケージがあなたのパッケージに依存している場合(あなたがアプリケーションではなくライブラリを作成した場合)、それらのパッケージも "flat": truepackage.json 内に含めるか、コマンドラインで yarn install --flat によってインストールされる必要があることに注意してください。

resolutions

{
  "resolutions": {
    "transitive-package-1": "0.0.29",
    "transitive-package-2": "file:./local-forks/transitive-package-2",
    "dependencies-package-1/transitive-package-3": "^2.1.1"
  }
}

特定のネストした依存関係のバージョンをオーバーライドすることができます。 詳細な仕様については、Selective Versions Resolutions RFC をご覧ください。

[yarn install --flat] コマンドで依存関係をインストールした場合、resolutions ブロックが package.json ファイルに自動的に追加されることに注意してください。

システム

OSの互換性のような、パッケージに関連するシステムレベルの情報を提供することができます。

engines

{
  "engines": {
    "node": ">=4.4.7 <7.0.0",
    "zlib": "^1.2.8",
    "yarn": "^0.14.0"
  }
}

パッケージで必須とされるクライアントのバージョンを指定します。これは、yarn の現在のバージョンだけでなく、process.versions に対しても照合されます。

このチェックでは普通のセマンティックバージョニングのルールが適用されますが、1つ例外があります。 プリリリースのバージョンを指定した場合、明示的にプリリリースの値が書かれていないバージョンにもマッチします。 たとえば、1.4.0-rc.0>=1.3.0 にマッチしますが、通常のセマンティックバージョンにはマッチしません。

os

{
  "os": ["darwin", "linux"],
  "os": ["!win32"]
}

パッケージのための OS の互換性を指定します。process.platform に対して照合されます。

cpu

{
  "cpu": ["x64", "ia32"],
  "cpu": ["!arm", "!mips"]
}

パッケージが特定の CPU アーキテクチャでのみ実行することを指定するのに使用します。process.arch に対して照合されます。

公開

private

{
  "private": true
}

パッケージマネージャーであなたのパッケージを公開したくない場合に、true を設定します。

publishConfig

{
  "publishConfig": {
    ...
  }
}

これらの設定値はあなたのパッケージが公開される際に使用されます。例えば、パッケージのタグなどの指定が可能です。