パッケージの作成

package とは、コードと、Yarn にパッケージに関する情報を提供する package.json ファイルが入ったディレクトリです。

ほとんどのパッケージは、何らかのバージョン管理システムを使用しています。もっとも一般的なものは git ですが、Yarn はいずれを選んでもそれを気にすることはありません。このガイドでは、例において git を使用します。

注意: このガイドに従って進みたい場合は、まず git および Yarn を必ずインストールしてください。

最初のパッケージを作成する

初めてのパッケージを作成するには、システムのターミナル/コンソールを開いて、以下のコマンドを実行します。

git init my-new-project
cd my-new-project
yarn init

これにより、新しい git リポジトリを作成し、その中に入り、それから対話形式で以下の質問を行って新しい yarn プロジェクトを作成します。

name (my-new-project):
version (1.0.0):
description:
entry point (index.js):
git repository:
author:
license (MIT):

これら各々を入力するか、デフォルト値を使うか空白のままにしておくなら、 enter/return を押すだけで回答することができます。

Tip: 全てにデフォルト値を使用したいなら、yarn init --yes を実行して全ての質問をスキップすることができます。

package.json

これで下記と同じような package.json が生成されているはずです。

{
  "name": "my-new-project",
  "version": "1.0.0",
  "description": "My New Project description.",
  "main": "index.js",
  "repository": {
    "url": "https://example.com/your-username/my-new-project",
    "type": "git"
  },
  "author": "Your Name <you@example.com>",
  "license": "MIT"
}

package.json 内のフィールドの意味を以下に説明します:

  • name はパッケージを識別するもので、グローバルなレジストリに公開するつもりなら、必ずこれをユニークなものにする必要があります。
  • version は semver 表現と互換性のあるパッケージのバージョン表記であり、必要なだけパッケージを公開することができますが、それらは必ず新しいバージョンでなければなりません。
  • description は省略可能ですが、他の Yarn ユーザーがあなたのプロジェクトを発見し、理解するためのものなので、記述することをお勧めします。
  • main は Node.js のようなプログラムが、あなたのコードを使用する際のエントリポイントを定義するのに使用されます。指定されなければデフォルトでは index.js となります。
  • repository はもう1つの省略可能なフィールドですが、パッケージの利用者がコントリビュートする際にソースコードを見つけるためのものなので、記述することをお勧めします。
  • author はパッケージの作成者もしくは管理者です。"Your Name <you@example.com> (http://your-website.com)" のフォーマットに従います。
  • license は、パッケージおよび、パッケージ内のコードの許諾される利用方法についての、公開の法的な文章です。

yarn initの実行で行われることは、このファイルを作成することだけです。バックグラウンドで何も行われません。あなたは好きなようにこのファイルを編集することができます。

追加のフィールド

あなたが必要とするかもしれない、 package.json への追加のフィールドを見ていきましょう。

{
  "name": "my-new-project",
  "...": "...",
  "keywords": ["cool", "useful", "stuff"],
  "homepage": "https://my-new-project-website.com",
  "bugs": "https://github.com/you/my-new-project/issues",
  "contributors": [
    "Your Friend <their-email@example.com> (http://their-website.com)",
    "Another Friend <another-email@example.com> (https://another-website.org)"
  ],
  "files": ["index.js", "lib/*.js", "bin/*.js"],
  "bin": {
    "my-new-project-cli": "bin/my-new-project-cli.js"
  }
}
  • keywords は、他の開発者があなたのパッケージ、もしくは関連するパッケージを探すのに利用する、用語のリストです。
  • homepage は、パッケージの紹介やドキュメント、そして追加資料へのリンクがあるウェブサイトへと、ユーザーを誘導する url です。
  • bugs はパッケージの問題を発見した場合に、ユーザーを誘導するための url です。
  • contributors はパッケージのコントリビュータのリストです。あなたの他にプロジェクトに関わった人がいる場合は、ここで彼らを表示することができます。
  • files は公開時およびインストール時に、パッケージに含まれる必要があるファイルのリストです。指定がなければ Yarn は全てのファイルをパッケージに含みます。
  • bin はパッケージのインストール時に Yarn が 作成する cli コマンド(バイナリ)の対応表です。

package.json の全てのフィールドのリストと、上記のフィールドのさらなる詳細については、package.json のドキュメント を参照してください。

ライセンスとオープンソース

一般的に Yarn パッケージはオープンソース化することが推奨されていますが、単に公開するだけでは本質的にオープンソース化されたことにはなりません。

コードをオープンソース化するには、オープンソースライセンスを設定する必要があります。選ぶことのできるオープンソースライセンスは沢山ありますが、一般的なものをいくつか紹介します:

もっと多くの選択肢が欲しいなら、こちらにより完全なリストがあります。

パッケージに適用するオープンソースライセンスを選んだら、必ずパッケージのルートにライセンスの内容を記述した LICENSE ファイルを追加して、 package.jsonlicense フィールドを更新してください。

注意: プロジェクトをオープンソース化したくない場合は、どのようなライセンスを設定するのか、もしくはライセンスを設定しないことを明示してください。

コードの共有

パッケージのユーザーがソースコードにアクセスして、問題を報告できるようにしたい事があるでしょう。コードをホスティングできるウェブサイトで、人気のあるものをいくつか示します。

これらのサイトでユーザーは、コードを確認したり、問題をレポートしたり、そしてコントリビュートしたりできます。どこかにコードをアップロードしたなら、以下のフィールドを package.json に追加してください:

{
  "homepage": "https://github.com/username/my-new-project",
  "bugs": "https://github.com/username/my-new-project/issues",
  "repository": {
    "url": "https://github.com/username/my-new-project",
    "type": "git"
  }
}

ドキュメント

理想的には、パッケージを公開する前にドキュメントを整備しておくべきです。 少なくとも、パッケージの紹介とパブリック API をまとめた README.md ファイルをプロジェクトルートに作成するべきです。

良いドキュメントの定義とは、プロジェクトを使い始め、そして使い続けるのに必要な全ての知識をユーザーに与えるようなドキュメントであることです。 あなたのプロジェクトの事を何も知らない人が持つであろう疑問について、考えるようにしてください。 物事を正確にそして必要なだけ詳細を説明し、なおかつ読みやすく簡潔に保つよう心がけてください。 品質の高いドキュメントを備えたプロジェクトは、はるかに多くの成功を得るものです。

パッケージを小さく保つ

Yarn パッケージを作成する際は、パッケージを小さく、そしてシンプルに保つことをお勧めします。 そうする意義があるなら、大きなパッケージを多数の小さなものに分割してください。 Yarn は何百、何千というパッケージを効率よくインストールすることができるので、分割することを強くお勧めします。

多数の小さなパッケージにすることは、パッケージ管理の素晴らしいモデルです。これにより、大規模な依存関係を構築することなく小さな部品だけを利用する事になるため、ダウンロードサイズを削減する結果につながります。

パッケージの内容についても考える必要があります。 誤ってテストコードや、その他のパッケージの利用時に不要なファイル(ビルドスクリプトや画像など)を配信してしまわないようにしてください。

どのパッケージに依存しているのかについても注意を払い、それができない十分な理由がない限りはなるべく依存関係を小さくするようにしてください。誤って何らかの大規模なものに依存してしまわないようにしてください。