JavaScript
npm
package-lock.json

package-lock.jsonの各プロパティについて調べてみました。

JavaScript Advent Calendar 2017 13日目の記事です。

今年はnpmが5にメジャーアップデートされました。
npm5になり新しく加わった機能の一つにpackage-lock.jsonがあります。
他の機能についてはこちら(npm v5 がリリースされた)

今回はpackage-lock.jsonの各プロパティについて詳しく載っている日本語記事が無かったので調べてみました。
内容に不備があったり気づいたことがあればどんどんコメントください。

きっかけ

package-lock.jsonについては依存パッケージの固定化する機能であったり、元々はnpm-shrinkwrapというものがあってそれを改良したものであったり等は聞いたり読んだりしたことある方は多いかと思います。
私も「依存パッケージの固定ができるなんて便利だな、公式もコミットするのを推奨しているしgit管理するか」ぐらいの軽いノリでpackage-lock.jsonをコミットしていたのですが、macos環境とLinux環境でoptionalDepndenciesが入ったり入らなかったり、requiresというプロパティが増えたり、package.jsonに変更がなくてもpackage-lock.jsonが意図せず変更されるることがありました。
そういった時に中身を見てみるのですが、何が何だかわからず読めなかったので調べてみました。

各プロパティについて

公式の完全翻訳ではありません。
省略していたり追記している部分がありますが、公式をベースに説明していきます。

name

パッケージの名称です。
package.jsonに記載されいてるnameが自動で設定されます。

version

パッケージのバージョンです。
package.jsonに記載されているversionが自動で設定されます。
ちょっと話は逸れますが、依存パッケージのバージョンを上げる際はsemverに従ってアップデートしてください。

lockfileVersion

package-lock.json自体のバージョンです。ロックするフォーマットの形式が将来変わった場合にどのバージョンのロック形式かわかるようにするためです。
1から始まる整数が設定されます。

packageIntegrity

package.jsonのSubresource Integrity(SRI)です。SRIの値はssriのようなモジュールによって生成可能です。

preserveSymlinks

NODE_PRESERVE_SYMLINKSという環境変数を使ってパッケージをインストールする場合、インストーラーはこの値が環境変数と一致する必要があるみたいです。

dependencies

依存関係のマッピング。ここに記載されたパッケージの定義に従いnode_modulesにパッケージをインストールします。
各依存関係のマッピングには以下のプロパティが定義されています。

version

依存パッケージのバージョンです。
npmレジストリに登録されている場合は1.2.3のようなバージョン番号になります。githubから取得する場合はgit+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97eのようになり、リモートアーカイブから取得する場合はhttps://example.com/example-1.3.0.tgzのようになります。

integrity

依存パッケージのSubresource Integrity(SRI)です。githubから取得する場合はコミットのハッシュ、リモートアーカイブから取得した場合はファイルをSHA-512で暗号化したハッシュ値です。

resolved

npmレジストリ上の特定のファイルが使用可能な場合はここに記載されたURL先のファイルを使用します。存在しない場合はversionを使用して依存解決します。

bundled

該当しない場合はこのプロパティは記述されません。
true: このパッケージは独立してインストールされるわけではなく親モジュールの圧縮パッケージが解凍されるときに親モジュールから直接取り出されます。

dev

devDependenciesに指定されているパッケージの依存パッケージの場合のみこのプロパティは記述されます。
true: devDependenciesとして指定されているパッケージからの参照の場合のみ
false: devDependenciesからのパッケージだけに限らず、devDependencies以外からも参照されている場合

optional

optionalDependenciesに指定されているパッケージの依存パッケージの場合のみこのプロパティは記述されます。
true: optionalDependenciesとして指定されているパッケージからの参照の場合のみ
false: optionalDependenciesからのパッケージに限らず、optionalDependencies以外からも参照されている場合

requires

公式にはありませんが、GitHubには説明が記載されています。
npm 5.1.0から追加されました。(リリースノート
このモジュールが必要とするすべてのパッケージが、どこからインストールされたかに関係なく、名前: バージョン番号の形式で一覧で記載されます。
各パッケージが参照する特定のバージョンへの参照が記載されています。package-lock.json以外の他のロックファイルやフォーマットへの変換や最適化、パッケージツリーの正確性の検証などさまざまな用途に使用されます。
npmjs.comでパッケージを検索した際に表示されているDependenciesの内容と一致します。

参考

以上になります。
package-lockの運用や内容の理解に困っている方の一助になれば幸いです。
今回の調査によって私も勉強になりました。
また、package-lock.jsonの運用が固まってきて良い感じになってきたら記事にしたいと思います。
最後までお読み頂きありがとうございました。