依存関係のバージョン

セマンティックバージョニング

Yarn にあるパッケージは、 “semver” としても知られるセマンティックバージョニングの規則に従います。 レジストリから新しいパッケージをインストールした場合、そのパッケージは package.json ファイルに sember のバージョンの範囲で追加されます

これらのバージョンは major.minor.patch に分解され次のような形になります: 3.14.10.42.02.7.18。 バージョンの各パートは様々なタイミングでインクリメントされます:

  • major バージョンのインクリメントは、パッケージの API に対して廃止もしくは互換性の無い変更を行った場合に行われる
  • minor バージョンのインクリメントは後方互換性を維持しながら新しい機能を追加した場合に行われる
  • patch バージョンのインクリメントは後方互換性を維持しながらバグを修正した場合に行われる

注意: 時にリリース前やベータ版(例えば 2.0.0-beta.3)などをマークするために、 semver フォーマットへの「ラベル付け」または「拡張」が行われることもあります。

開発者がお互いに「互換性」がある2つの semver について話している場合は、後方互換性のある変更(minor および patch)を参照しています。

バージョンの範囲

依存関係を指定したい場合、そのパッケージ名と バージョン範囲 を下記のいずれかのように、 package.json で指定します:

{
  "dependencies": {
    "package-1": ">=2.0.0 <3.1.4",
    "package-2": "^0.4.2",
    "package-3": "~2.7.1"
  }
}

バージョンとは別の文字の集まりがあることに気づくでしょう。 これらの文字、 >=<^ そして ~演算子であり、バージョン範囲を指定するためのものです。

バージョン範囲の目的は、依存関係のどのバージョンがあなたのコードと動作するのかを指定することです。

比較演算子

バージョン範囲は各々比較演算子により構成されます。これらの比較演算子はバージョンが後に続く単なる演算子です。以下に基本的な演算子の一部を示します:

比較演算子 説明
<2.0.0 2.0.0 以前の任意のバージョン
<=3.1.4 3.1.4 もしくはそれ以前の任意のバージョン
>0.4.2 0.4.2以降の任意のバージョン
>=2.7.1 2.7.1 もしくはそれ以降の任意のバージョン
=4.6.6 バージョン4.6.6のみ

注意: 演算子が指定されない場合、 = がバージョン範囲として推定されます。そのため、= は実際には省略可能です。

比較演算子の交差

比較演算子は空白スペースと組み合わせて、比較演算子のセットを作成できます。 これにより、比較演算子を交差させることができます。 例えば、比較演算子のセット >=2.0.0 <3.1.42.0.0 もしくはそれ以降で、かつ 3.1.4 以前であること」を意味します。

比較演算子の結合

全てのバージョン範囲は複数の比較演算子のセットを || で繋いで結合させることができます。 結合したものの一方が満たされれば、バージョン範囲全体が満たされたことになります。 例えば、バージョン範囲 <2.0.0 || >3.1.42.0.0 以降または 3.1.4 以前であること」を意味します。

リリース前のタグ

バージョンは リリース前のタグ(例えば 3.1.4-beta.2)を持つこともできます。 比較演算子がリリース前のタグを持つバージョンを含んでいる場合、同じ major.minor.patch のバージョンを持つバージョンにだけ一致します。

例えば、範囲 >=3.1.4-beta.23.1.4-beta.2 もしくは 3.1.4-beta.12 に一致しますが、 3.1.5-beta.1 には、たとえ数字の上ではバージョン 3.1.4-beta.2 と「等しいかそれ以降」 (>=) であっても、一致しません

リリース前のものは偶発的に破壊的な変更が含まれていることがよくあります。このため通常は指定したバージョン以外の、リリース前のバージョンに一致させたくないはずなので、この動作は役に立ちます。

高度なバージョンの範囲

ハイフンによる範囲の表現

ハイフンによる範囲の表記(例えば 2.0.0 - 3.1.4)は包括的なセットを指定します。バージョンの一部が省略されている場合(例えば 0.4 もしくは 2)、ゼロで埋められます。

バージョン範囲 展開されたバージョンの範囲
2.0.0 - 3.1.4 >=2.0.0 <=3.1.4
0.4 - 2 >=0.4.0 <=2.0.0
Xによる範囲の表現

Xx もしくは * のいずれかを、バージョンの一部または全部を指定せずにおくのに使用できます。

バージョン範囲 展開されたバージョンの範囲
* >=0.0.0 (任意のバージョン)
2.x >=2.0.0 <3.0.0 (メジャーバージョンが一致)
3.1.x >=3.1.0 <3.2.0 (メジャーおよびマイナーバージョンが一致)

バージョンの一部が省略されている場合、x 範囲であると推定されます。

バージョン範囲 展開されたバージョンの範囲
`` (空の文字列) * もしくは >=0.0.0
2 2.x.x もしくは >=2.0.0 <3.0.0
3.1 3.1.x もしくは >=3.1.0 <3.2.0
チルダによる範囲の表現

~ を用いてマイナーバージョンまでを指定すると、patch バージョンの変更を許容します。メジャーバージョンと ~ のみの表記は minor バージョンの変更を許容します。

バージョン範囲 展開されたバージョンの範囲
~3.1.4 >=3.1.4 <3.2.0
~3.1 3.1.x もしくは >=3.1.0 <3.2.0
~3 3.x or >=3.0.0 <4.0.0

注意: チルダとリリース前のバージョンによる表記は同じバージョンのリリース前のものにのみ一致します。 例えばバージョン範囲 ~3.1.4-beta.23.1.4-beta.4 に一致しますが、3.1.5-beta.2 には一致しません。これは major.minor.patch のバージョンが異なるためです。

キャレットによる範囲の表現

最初のゼロでない桁、3.1.43 もしくは 0.4.24 などが変わらない、バージョンの変更を許容します。

バージョン範囲 展開されたバージョンの範囲
^3.1.4 >=3.1.4 <4.0.0
^0.4.2 >=0.4.2 <0.5.0
^0.0.2 >=0.0.2 <0.0.3

注意: デフォルトでは yarn add [package-name] を実行した場合、キャレットによる範囲が使用されます。

バージョンの一部が省略された場合、足りない部分はゼロで埋められます。しかし、その値が変更になることも許容します。

バージョン範囲 展開されたバージョンの範囲
^0.0.x >=0.0.0 <0.1.0
^0.0 >=0.0.0 <0.1.0
^0.x >=0.0.0 <1.0.0
^0 >=0.0.0 <1.0.0

追加資料

  • このバージョン番号を管理するシステムの動作の完全な仕様については、node-semver の READMEを参照してください。
  • npm semver calculator を使用して実際のパッケージで、このバージョン番号の管理システムを試してください。