Bunのbun.lockとnpmのpackage-lock.jsonの違い

​​Bun​Node.js,npm,パッケージ管理

bun.lock と package-lock.json は、どちらも入れたパッケージのバージョンと integrity(中身のハッシュ)を記録するファイルです。記録の中身はほぼ同じですが、書き方と、互いのファイルを読むかどうかが違います。Bun は package-lock.json を読めますが、npm は bun.lock を読まず、package.json から入れ直します。

npm から Bun に乗り換えるときや、CI で依存のバージョンを固定したいときに、ロックファイルをどう扱えばよいかをまとめました。私は検証環境で、同じ package.json から2つのファイルを作り、中身と動きを比べました。

補足

検証環境は Ubuntu 24.04(x86_64)、Node.js 22.23.4(npm 10.9.9)、Bun 1.4.4 です。パッケージは registry.npmjs.org から取得しました。workspaces を使うプロジェクト、git: や file: の依存、古い形式の bun.lockb、Windows と macOS は試していません。Bun と npm の公式ドキュメントは、検証に使った版(Bun はタグ bun-v1.4.4、npm はタグ v10.9.9)の元ファイルを GitHub で確認しています。

同じ package.json から作った2つのファイル

依存が2つだけの package.json を、npm 用と Bun 用の2つのフォルダに置きました。

json
{
  "name": "lock-demo",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "debug": "^4.3.7",
    "chalk": "^5.3.0"
  }
}

それぞれのフォルダで npm install と bun install を実行しました。どちらも chalk 5.6.2、debug 4.4.3、debug が依存している ms 2.1.3 の3つを入れています。できたロックファイルの大きさは次のとおりです。

text
$ wc -c -l n/package-lock.json b/bun.lock
  51 1457 n/package-lock.json
  20  751 b/bun.lock

package-lock.json は 51 行、1,457 バイトで、bun.lock は 20 行、751 バイトでした。bun.lock の全体は次のとおりです。

text
{
  "lockfileVersion": 2,
  "configVersion": 1,
  "workspaces": {
    "": {
      "name": "lock-demo",
      "dependencies": {
        "chalk": "^5.3.0",
        "debug": "^4.3.7",
      },
    },
  },
  "packages": {
    "chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],

    "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" }, "peerDependencies": { "supports-color": "*" }, "optionalPeers": ["supports-color"] }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],

    "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
  }
}

1つのパッケージの書き方の違い

同じ ms 2.1.3 を、package-lock.json は次のように書いていました。

json
"node_modules/ms": {
  "version": "2.1.3",
  "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
  "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
  "license": "MIT"
}

bun.lock では、1つのパッケージが1行の配列になっています。

text
"ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],

比べると、違いは次の3つでした。

項目 package-lock.json bun.lock
キー node_modules/ms(入れる場所) ms(パッケージの名前)
ダウンロード元の URL resolved に tarball の URL を書く 2番目の要素が空の文字列で、URL は書いていない
ライセンスや対応する Node.js のバージョン license を書く(chalk と debug では engines も) 書いていない

integrity の値は、3つのパッケージとも2つのファイルでまったく同じでした。キーの違いについては、package-lock.json の公式ドキュメントにも、packages の各項目のキーは、プロジェクトのフォルダからの相対パスにすると書かれています。

もう1つの違いは、bun.lock は最後の要素のあとにもカンマを付けることです。そのため、Node.js の JSON.parse では読めません。

text
$ node -e 'JSON.parse(require("fs").readFileSync("b/bun.lock","utf8")); console.log("ok")'
(中略)
SyntaxError: Expected double-quoted property name in JSON at position 187 (line 10 column 7)
(以下、スタックトレースが続くので省略)

package-lock.json は同じコマンドで読めました。Bun 用のフォルダで Bun を使うと、require("./bun.lock") で読み込めて、lockfileVersion と packages のキーを取り出せました。

text
$ bun -e 'const l = require("./bun.lock"); console.log(l.lockfileVersion, Object.keys(l.packages))'
2 [ "chalk", "debug", "ms" ]

依存を1つ足したときの差分

どちらのフォルダも git で一度コミットしてから、npm install picocolors と bun add picocolors で picocolors 1.1.1 を足しました。git diff --stat の結果は、npm のフォルダでは次のとおりです。

text
$ git diff --stat
 package-lock.json | 9 ++++++++-
 package.json      | 3 ++-
 2 files changed, 10 insertions(+), 2 deletions(-)

Bun のフォルダでは次のとおりです。

text
$ git diff --stat
 bun.lock     | 3 +++
 package.json | 3 ++-
 2 files changed, 5 insertions(+), 1 deletion(-)

ロックファイルの変更は、package-lock.json が8行の追加と1行の削除、bun.lock が3行の追加だけでした。bun.lock の差分は次のとおりです(ハッシュは途中を省略しています)。

diff
       "dependencies": {
         "chalk": "^5.3.0",
         "debug": "^4.3.7",
+        "picocolors": "^1.1.1",
       },
(中略)
     "ms": ["ms@2.1.3", "", {}, "sha512-6Flz…"],
+
+    "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH…"],

package-lock.json の1行の削除は、"debug": "^4.3.7" の行です。後ろに picocolors の行が加わったため、カンマを付けた行に書き換わっていました。bun.lock は最後の行にもカンマがあるので、元の行は変わらず、足した行だけが差分に出ています。

package.json とロックファイルが食い違ったとき

CI では、ロックファイルどおりに入れ、package.json と合わなければ止める使い方をします。npm では npm ci、Bun では bun ci です。bun install の公式ドキュメントによると、bun ci は bun install --frozen-lockfile と同じ動きです。

package.json の dependencies に "is-number": "^7.0.0" を手で書き足し、ロックファイルは更新しないまま実行しました。

text
$ npm ci --no-audit --no-fund
npm error code EUSAGE
npm error
npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
npm error
npm error Missing: is-number@7.0.0 from lock file
(使い方の説明が続くので省略)
text
$ bun ci
bun install v1.4.4 (38afee6c8)
error: lockfile had changes, but lockfile is frozen
note: dependencies in package.json changed since bun.lock was saved: is-number was added
note: try re-running without --frozen-lockfile and commit the updated lockfile

どちらも終了コード 1 で止まり、ロックファイルは書き換えませんでした(git status で変わっていたのは package.json だけです)。bun install --frozen-lockfile でも、bun ci と同じメッセージが出ました。

次に、依存を足すのではなく、debug の範囲を ^4.3.7 から >=4.3.7 に変えただけで試しました。ロックファイルにある debug 4.4.3 は、どちらの範囲にも入ります。このときは、npm ci も bun ci も止まらずに入れ終わりました。

text
$ bun ci
bun install v1.4.4 (38afee6c8)

Checked 4 installs across 5 packages (no changes) [1.00ms]

Bun の同じ公式ドキュメントにも、入るバージョンが変わらない書き換え(^1.0.0 を >=1.0.0 にするなど)では止まらないと書かれています。

npm は bun.lock を読まない

bun.lock で chalk を 5.3.0 に固めたフォルダを作り、npm と Bun で入れ比べました。package.json の範囲は ^5.3.0 で、レジストリにはこの範囲に入る 5.6.2 があります。

text
$ grep -A3 '"packages"' bun.lock
  "packages": {
    "chalk": ["chalk@5.3.0", "", {}, "sha512-dLitG79d+GV1Nb/VYcCDFivJeK1hiukt9QjRNVOsUtTy1rR1YJsmpGGTZ3qJos+uw7WmWF4wUwBd9jxjocFC2w=="],
  }
}

このフォルダを2つに写し、node_modules を消してから、それぞれ npm install と bun ci を実行しました。入った chalk のバージョンは次のとおりです。

text
$ npm install --no-audit --no-fund && node -p 'require("./node_modules/chalk/package.json").version'

added 1 package in 256ms
5.6.2
text
$ bun ci && node -p 'require("./node_modules/chalk/package.json").version'
bun install v1.4.4 (38afee6c8)

+ chalk@5.3.0

1 package installed [1.00ms]
5.3.0

npm は bun.lock を使わずに package.json の範囲から選び直し、5.6.2 を入れました。フォルダには新しく package-lock.json ができ、bun.lock もフォルダに残っていました。bun.lock だけがあるフォルダで npm ci を実行すると、package-lock.json がないというエラーで止まりました。

text
$ npm ci --no-audit --no-fund
npm error code EUSAGE
npm error
npm error The `npm ci` command can only install with an existing package-lock.json or
npm error npm-shrinkwrap.json with lockfileVersion >= 1. Run an install with npm@5 or
npm error later to generate a package-lock.json file, then try again.
(使い方の説明が続くので省略)
注意

bun.lock だけをコミットしたプロジェクトで、誰かが npm install を実行すると、ロックファイルで固めたものとは違うバージョンが入ることがあります。プロジェクトで使うパッケージマネージャーを、npm か Bun のどちらかにそろえておく必要があります。

Bun は package-lock.json を読む

逆に、package.json と package-lock.json だけがあるフォルダで bun ci を実行すると、Bun は package-lock.json を読み込んで入れました。

text
$ bun ci
bun install v1.4.4 (38afee6c8)
[0.32ms] migrated lockfile from package-lock.json

+ chalk@5.6.2
+ debug@4.4.3
+ picocolors@1.1.1

4 packages installed [2.00ms]

ロックファイルについての Bun の公式ドキュメントによると、bun ci と bun install --frozen-lockfile は、読み込んだ package-lock.json をメモリの上で bun.lock に変えて使うだけで、ファイルには書き出しません。bun.lock を作るには、フラグを付けずに bun install を実行するか、bun pm migrate を実行します。どちらでも、元の package-lock.json は消されずに残ります。同じドキュメントによると、Bun 1.2 からはテキストの bun.lock が標準で、それより前のバイナリの bun.lockb については、bun install --save-text-lockfile --frozen-lockfile --lockfile-only で bun.lock に変えてから、bun.lockb を消す手順が案内されています。

検証環境でも、bun ci のあとのフォルダにあったのは package.json、package-lock.json、node_modules の3つで、bun.lock はできていませんでした。

​Posted by 86