npm パッケージの小さな修正を patch-package で管理する

Headless CMS を使ったサービスを制作していたところ、使用している npm パッケージにバグが見つかりました。
GitHub を確認すると、同じ問題の issue は上がっていましたが、しばらく対応されていないようです。原因は1か所 new が抜けているだけなので、npm install の後にファイルを修正すれば動きます。
ただ、インストールするたびに修正する運用は、忘れてしまいそうです。Docker イメージのビルド時にも同じ修正が必要になります。
そこで、npm パッケージへの変更をパッチとして管理できる patch-package を使うことにしました。
patch-package をインストールする
まず、patch-package をインストールします。今回は開発・ビルド時に適用する想定で、devDependencies に追加しました。
npm install --save-dev patch-package次に、package.json の scripts に postinstall を追加します。
{
"scripts": {
"postinstall": "patch-package"
}
}これで、通常の npm install や npm ci の後に patch-package が実行されます。
すでに postinstall がある場合は、既存の処理を残したうえで追加してください。
パッケージを修正してパッチを作る
次に、node_modules 内の対象パッケージを修正します。今回の問題では、抜けていた new を追加しました。
修正後、次のコマンドを実行します。
npx patch-package <パッケージ名>すると、プロジェクトの patches ディレクトリに、元のパッケージと修正後の差分がパッチファイルとして生成されます。
patches/
└── package-name+1.2.3.patch生成されたパッチファイルを package.json やロックファイルと一緒にプロジェクトで管理しておけば、依存パッケージの再インストール時にも修正を適用できます。[patch-package の公式リポジトリ]
Docker ビルドで使う場合
Docker イメージのビルド時にも、postinstall を使ってパッチを適用できます。
その際、npm ci を実行する前に patches ディレクトリをイメージ内へコピーしておく必要があります。
COPY package.json package-lock.json ./
COPY patches ./patches
RUN npm ciまた、patch-package を devDependencies に入れた場合、npm ci --omit=dev のように開発用パッケージを省略すると、postinstall の実行時に patch-package が見つからない可能性があります。
本番環境で依存パッケージをインストールする場合は、patch-package を dependencies に入れる方法や、開発用依存関係を含むビルド段階でパッチを適用する方法を、構成に合わせて検討します。[patch-package の Docker・CI 向け案内]
パッケージ更新時にも確認する
パッチは、修正したパッケージのバージョンと内容を前提に作られます。そのため、パッケージを更新した際は、パッチを適用できるか、元のバグが修正済みかを確認する必要があります。
今回は小さな修正でしたが、インストール後に毎回手作業で直す必要がなくなり、Docker でのビルドにも組み込めました。依存パッケージの修正を一時的に管理したいときに便利です。




Discussion