Bunのbun patchで依存パッケージを直して使う方法
依存している npm パッケージに不具合があり、修正版が出るまで手元で直して使いたいときは、Bun の bun patch が使えます。bun patch <パッケージ名> を実行してから node_modules の中を直し、bun patch --commit を実行すると、変更が patches/ に .patch ファイルとして残ります。あとは bun install のたびに、そのパッチを当てたものが入ります。
公式ドキュメントの bun patch のページの手順を、私が検証環境で1つずつ実行し、package.json・bun.lock・キャッシュがどう変わるかを確かめました。
検証環境は Ubuntu 24.04(x86_64)、Bun 1.4.4 です。パッケージは registry.npmjs.org から取得しました。Bun のキャッシュは、検証のために空のフォルダを環境変数 BUN_INSTALL_CACHE_DIR で指定して使いました。workspaces を使ったモノレポ、bun patch-commit(pnpm と同じ名前のコマンド)、Windows と macOS は試していません。
直す例にしたパッケージ
時間の長さを「2m」のような短い文字列にする ms の 2.1.3 を使いました。ms(90_000) は 1.5 分ですが、表示は四捨五入されて「2m」になります。これを小数第1位まで出すように直します。
import ms from "ms";
console.log(ms(90_000), ms(5_400_000), ms(36 * 3_600_000));
$ bun add ms@2.1.3
bun add v1.4.4 (38afee6c8)
Resolving dependencies
Resolved, downloaded and extracted [4]
Saved lockfile
installed ms@2.1.3
1 package installed [64.00ms]
$ bun index.ts
2m 2h 2d
直すのは、node_modules/ms/index.js の fmtShort という関数です。
bun patch で直す準備をする
最初に bun patch ms を実行します。
$ bun patch ms
bun patch v1.4.4 (38afee6c8)
Checked 1 install across 2 packages (no changes) [0.00ms]
To patch ms, edit the following folder:
node_modules/ms
Once you're done with your changes, run:
bun patch --commit 'node_modules/ms'
この時点では、package.json は何も変わりません。変わるのは、node_modules/ms のファイルとキャッシュのつながり方です。
Linux の Bun は、標準ではキャッシュのファイルを node_modules にハードリンクで置きます(bun patch のページにある CLI の説明の --backend の項)。stat でリンクの数と inode の番号を見ると、bun patch の前は node_modules の index.js とキャッシュの index.js が同じファイルでした。bun patch ms のあとは、node_modules の側が別のファイル(リンクの数 1)に変わりました。出力のキャッシュのパスは /path/to/work に置き換えています。
# bun patch の前
2 links, inode 615623, node_modules/ms/index.js
2 links, inode 615623, /path/to/work/cache/ms@2.1.3@@@1/index.js
# bun patch ms のあと
1 links, inode 615635, node_modules/ms/index.js
1 links, inode 615623, /path/to/work/cache/ms@2.1.3@@@1/index.js

node_modules の中を直して動きを確かめる
あとは node_modules/ms/index.js を直接書き換えます。今回は Math.round(ms / m) のような4か所を、Math.round(ms / m * 10) / 10 に変えました。
$ bun index.ts
1.5m 1.5h 1.5d
書き換えたのは node_modules の中だけです。キャッシュの index.js は元のままでした。この段階では、変更は node_modules の中にしかなく、package.json も変わっていません。この状態のプロジェクトを別のフォルダに写し、node_modules を消して bun install を実行し直すと、結果は「2m 2h 2d」に戻りました。
bun patch –commit でパッチのファイルにする
直し終わったら bun patch --commit ms を実行します。--dry-run を付けると、何が書き込まれるかだけを表示します。
$ bun patch --commit ms --dry-run
bun patch v1.4.4 (38afee6c8)
dry run: would write patches/ms@2.1.3.patch and add ms@2.1.3 to patchedDependencies
--dry-run のあとに patches フォルダはなく、package.json も変わっていませんでした。付けずに実行すると、次のようになりました。
$ bun patch --commit ms
bun patch v1.4.4 (38afee6c8)
Resolving dependencies
Resolved, downloaded and extracted [1]
Saved lockfile
+ ms@2.1.3
1 package installed [5.00ms]
プロジェクトに patches/ms@2.1.3.patch ができました。中身は git の diff と同じ形式です。
diff --git a/index.js b/index.js
index ea734fb73820316ed1c0f6a2f6e96dce0e3eb6f0..b92279cf65aae163161be447788415b23c3b0cde 100644
--- a/index.js
+++ b/index.js
@@ -113,16 +113,16 @@ function parse(str) {
function fmtShort(ms) {
var msAbs = Math.abs(ms);
if (msAbs >= d) {
- return Math.round(ms / d) + 'd';
+ return Math.round(ms / d * 10) / 10 + 'd';
}
if (msAbs >= h) {
- return Math.round(ms / h) + 'h';
+ return Math.round(ms / h * 10) / 10 + 'h';
}
if (msAbs >= m) {
- return Math.round(ms / m) + 'm';
+ return Math.round(ms / m * 10) / 10 + 'm';
}
if (msAbs >= s) {
- return Math.round(ms / s) + 's';
+ return Math.round(ms / s * 10) / 10 + 's';
}
return ms + 'ms';
}
package.json と bun.lock には、patchedDependencies が足されました。キーが「パッケージ名@バージョン」、値がパッチのファイルの場所です。
{
"name": "patch-app",
"private": true,
"dependencies": {
"ms": "2.1.3"
},
"patchedDependencies": {
"ms@2.1.3": "patches/ms@2.1.3.patch"
}
}
キャッシュには、元の ms@2.1.3@@@1 とは別に、ms@2.1.3@@@1_patch_hash=120c86b12dcd456d というフォルダが増えました。node_modules/ms/index.js は、こちらとハードリンクでつながっていました。元の ms@2.1.3@@@1 の index.js は、Math.round(ms / d) のままでした。
入れ直しても、別の場所で入れてもパッチが当たる
node_modules を消して bun install を実行し直しても、bun index.ts の結果は「1.5m 1.5h 1.5d」のままでした。
リポジトリを別のマシンで clone した状態に近づけるため、package.json・bun.lock・patches・index.ts だけを別のフォルダに写し、キャッシュも新しい(中身のない)フォルダにして bun install --frozen-lockfile を実行しました。ここでもパッチが当たり、結果は「1.5m 1.5h 1.5d」でした。キャッシュには、パッチを当てた ms@2.1.3@@@1_patch_hash=120c86b12dcd456d が新しく作られていました。チームで使うときは、patches フォルダも package.json・bun.lock と一緒にリポジトリにコミットします。
パッチのファイルを置く場所は、--patches-dir で変えられます。bun patch --commit ms --patches-dir=mypatches を実行すると、mypatches/ms@2.1.3.patch ができ、patchedDependencies の値も mypatches/ms@2.1.3.patch になりました。
patches フォルダを忘れると bun install が止まる
patchedDependencies に書かれたファイルがないと、bun install はエラーで止まりました(終了コード 1)。node_modules も作られませんでした。
$ bun install
bun install v1.4.4 (38afee6c8)
Resolving dependencies
error: patch file not found: 'patches/ms@2.1.3.patch'
To recreate it from the patched package in node_modules, run:
bun patch --commit ms@2.1.3
To install without the patch, remove "ms@2.1.3" from "patchedDependencies" in package.json
package.json だけをコミットして patches フォルダを入れ忘れると、ほかの人の環境や CI でこのエラーになります。
バージョンを変えるとパッチは当たらない
patchedDependencies には、パッチが ms@2.1.3 のようにバージョンまで含めた名前で登録されます。パッチを当てたプロジェクトを別のフォルダに写し、bun add ms@2.1.2 で別のバージョンに入れ替えると、警告が出ました。
$ bun add ms@2.1.2
bun add v1.4.4 (38afee6c8)
Resolving dependencies
Resolved, downloaded and extracted [3]
warn: patches/ms@2.1.3.patch no longer applies (ms is now 2.1.2)
Saved lockfile
installed ms@2.1.2
1 package installed [37.00ms]
bun index.ts の結果は「2m 2h 2d」に戻りました。package.json の patchedDependencies には "ms@2.1.3" が残ったままで、そのあと bun install を実行しても、同じ警告が出ました。修正版が出て依存を上げたときは、この警告を見て、いらなくなったパッチを外します。
パッチを外す
ここからは、ms 2.1.3 にパッチを当てた元のプロジェクトに戻ります。パッチを外すときは、もう一度 bun patch ms を実行し、node_modules/ms/index.js を元に戻してから bun patch --commit ms を実行します。
$ bun patch --commit ms
bun patch v1.4.4 (38afee6c8)
Saved lockfile
+ ms@2.1.3
1 package installed [4.00ms]
Removed the patch for ms@2.1.3 (deleted patches/ms@2.1.3.patch)
patches/ms@2.1.3.patch が消えて patches フォルダは空になり、package.json と bun.lock から patchedDependencies がなくなりました。bun index.ts の結果も「2m 2h 2d」に戻りました。公式ドキュメントには、patchedDependencies の行とパッチのファイルを自分で消してから bun install を実行する方法も書かれています。
bun patch を使わずに node_modules を書き換えたとき
公式ドキュメントは、先に bun patch を実行しないと、キャッシュの中のパッケージを書き換えてしまうことがあると注意しています。同じキャッシュを使う2つのプロジェクト a と b に ms 2.1.3 を入れ、b の node_modules だけを bun patch なしで書き換えて確かめました。
sed -i で書き換えた場合は、新しいファイルに置き換わるので(inode の番号が変わり、リンクの数が 3 から 1 になった)、プロジェクト a の結果は「2m 2h 2d」のままでした。
一方、ファイルを読んで同じファイルに書き戻す小さなスクリプトで書き換えた場合は、inode の番号もリンクの数も変わりませんでした。このときは、何もしていないプロジェクト a でも結果が「1.5m 1.5h 1.5d」に変わりました。キャッシュの ms@2.1.3@@@1/index.js も書き換わっていて、そのあと新しく作ったプロジェクトに bun add ms@2.1.3 で入れたものも、書き換わったものになりました。
node_modules の中を直すときは、書き換え方に関係なく、先に bun patch <パッケージ名> を実行します。





