Package.jsonの記述とpackage-lock.jsonについて #package.json

概要

Node.jsにおいてインストールするパッケージが記述されたJSONファイルです。パッケージ管理の設計書であり、異なる環境でもpackage.jsonを読み込むことで同じパッケージをインストールすることができます。

構成要素

以下、package.jsonの基本的な記述です。

package.json

{
  "name": "my-package",
  "description": "my first package ever",
  "license": "MIT",
  "version": "1.0.0",
  "bin": "./cli.js",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "axios": "^1.3.4"
  },
  "devDependencies": {
    "eslint": "^8.36.0"
  }
}

※name version description license などのデータはパッケージのメターデータなので、公開しないのであれば気にする必要は無いです。

機能的に重要なのは、bin main dependencies devDependencies scripts です。

bin

パケージを外から使うときに重要な項目。実行可能ファイルが指定されているとパッケージをインストールすれば、CLIとして実行できるようになります。

main

パッケージを外からインストールする時に、どのJSファイルが入り口であるかを指定するものです。外のパッケージを使う時に、どのファイルをインポートするということなのか確認できます。

scripts

任意のコマンドに名前を付けることができます。記載したscriptはnpm run <name>で実行できます。

dependencies

実行に必要なパッケージを記載します。一度npm iした状態でアップデートしたい場合は、直接package.jsonを編集せずにnpmを通じて行います。

また、npmでdependencyを変更すると自動的にpackage.jsonにも反映されます。
※もしpackage.jsonを直接編集した場合npm iを実行してnode_modules内のファイルを更新する必要があります。

追加
$ npm install <package>

削除
$ npm uninstall <package>

devDpendencies

開発やテストにのみ必要なパッケージを記載します。例えば、ESLintは開発のときにのみ必要で実行するときには不要なため、devDepに記載します。

$ npm install -D <package>

semver規格

npmはパッケージのバージョン管理をsemver(semantic versioning)と呼ばれる規格に従って行っています。semverによれば、全てのバージョンは3桁の数字で表記され、その形式は (x.y.z) です。パッケージの新バージョンがリリースされる場合、変更点・意味合いを踏まえて、それに合わせてバージョンを更新する必要があります。

x : メジャーバージョン
y : マイナーバージョン
z : パッチバージョン

大きな変更があった場合、新しい機能が実装された場合、メジャーバージョンを上げる。
後方互換性のある新機能が追加された場合、マイナーバージョンを上げる。
バグが修正された場合は、パッチバージョンを上げる。

バージョンアップのシンボル

セマンティックバージョンと一緒に、npmはpackage.jsonファイルでこれらのバージョンの前に特別なシンボルを追加します。これらのシンボルはnpm updateやnpm iを行うときにどのバージョンをインストールするかをnpmに伝えるために使用されます。

それぞれのシンボルには独自のルールがあり、パッケージをインストールする際にバージョンを解決する方法を定義しています。よく使われるシンボルには、カレット( ^ )とチルダ( ~ )があります。

カレット(^)

マイナーバージョンとパッチバージョンは変更可能ですが、メジャーバージョンは変更できません。例えば、package.jsonに^13.1.0と記載されている場合にnpm updateを行うと...

・13.2.0、13.3.0、13.3.1、13.3.2などのバージョンにはアップデートできますが、14.0.0やそれ以上のバージョンの変更を受付けないです。

チルダ

更新できるのはパッチバージョンだけです。例えば、package.jsonファイルに~13.1.0というバージョンがあった場合、npm updateを行うということになります、

13.1.1、13.1.3などのバージョンにアップデートすることができますが、13.2.0や13.3.0などのバージョンには適用されません。npmはデフォルトですべてのパッケージに^のルールを追加します。

なお、package.jsonで設定できる項目の全てはnpmドキュメントで確認でき、内容を訳してくれた記事もあります。

package-lock.jsonについて

dependencyのバージョンをlockするためのファイルです。npmを使用してパッケージをインストール/変更するときに自動的に生成されます。このファイルの主な目的は、インストールされたパッケージの正確なバージョンを追跡することです。また、副依存関係（インストールしたパッケージの依存関係として自動的にインストールされたパッケージ）についての情報も含まれます。

機能としてはnpm iを行う際、npmはpackage.jsonファイルをスキャンしてパッケージ名を見つけ、package-lock.jsonファイルをスキャンしてそのパッケージのバージョンを見つけます。lockファイルに記載されているバージョンとpackage.jsonファイルに記載されているバージョンが（semver記法に基づいて）互換性があると判断した場合、ロックファイルに記載されているバージョンのパッケージをインストールします。

なお、package-lock.jsonは直接編集せず、削除しないこと。