All posts

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