【テクニカル・上級編】npmの「prepare」と「prepublishOnly」の微妙な違い：公開前フックでリリース事故をゼロにする – ビルド・パッケージ管理ツール生産性向上バイブル

破壊的リリースを根絶する：npmライフサイクル・フックの深淵とCI/CDパイプラインの完全統治

npmのパッケージ管理において、`prepare` や `prepublishOnly` といったライフサイクルスクリプトを「なんとなく」で使い分けていないだろうか。もしそうであれば、それはあなたのリリースフローに「時限爆弾」を仕込んでいるのと同じだ。

今日は、npmの内部アーキテクチャと、それがCI/CDパイプラインやDockerコンテナとどう相互作用するのかを解き明かし、リリース事故をゼロにするための「鉄壁の自動化戦略」を授ける。

—

1. ライフサイクルスクリプトの「真の順序」と落とし穴

多くのエンジニアが混乱するのは、npmのフックが「どのタイミングで、どの権限で、どのコンテキスト（ローカルかCIか）で実行されるか」が複雑だからだ。特に重要な3つのフックの挙動を整理する。

ライフサイクル・マトリクス

ここが肝だ：
`prepare` は `npm install` 時に実行されるため、ローカル開発環境での利便性が高い一方、CI上の `npm install` でも走ってしまう。もしCIで `devDependencies` をインストールするフローを組んでいるなら、ここで重いビルド処理が走ることはパフォーマンスのボトルネックとなる。

—

2. 推奨される「鉄壁のビルド設計」：filesと.npmignoreの二段構え

意図しないファイル（テストコード、ソースマップ、秘密鍵等）の流出は、設定ファイルへの無理解から生じる。npmの公開メカニズムは、まず `package.json` の `files` フィールドをホワイトリストとして評価し、その後に `.npmignore` でフィルタリングを行う。

アーキテクトとしてのベストプラクティス：
`files` フィールドで「公開すべきもの」だけを明示的に指定する。`.npmignore` に依存するのは危険だ。

{
“name”: “@org/core”,
“version”: “1.0.0”,
“files”: [
“dist/”, // コンパイル済み成果物のみを許可
“README.md”,
“LICENSE”
],
“scripts”: {
“build”: “tsc –project tsconfig.build.json”,
“prepare”: “npm run build”, // インストール時に常に最新のビルドを生成
“prepublishOnly”: “npm test && npm run lint” // 公開直前にテストが通らなければ即時停止
}
}

—

3. CI/CDパイプラインとDockerの最適化：メモリ効率の極致

CI環境（GitHub ActionsやGitLab CI）で `npm install` を実行する際、`–frozen-lockfile` を使うのは当然の前提だ。しかし、さらに一歩先を行くには、「ビルドコンテナ」と「実行コンテナ」を分離するマルチステージビルドが不可欠である。

Dockerfileにおける効率的なビルド実装

ステージ1: ビルド環境（devDependenciesを含む）
FROM node:20-slim AS builder
WORKDIR /app
COPY package.json ./
RUN npm ci # ロックファイルによる厳密なインストール
COPY . .
RUN npm run build # prepareスクリプトをここで解決させる

ステージ2: 本番環境（最小限の依存関係のみ）
FROM node:20-slim
WORKDIR /app
COPY –from=builder /app/dist ./dist
COPY –from=builder /app/package.json ./
–productionフラグで不要な開発用パッケージを排除
RUN npm ci –only=production

この設計により、最終的なイメージサイズを劇的に削減し、かつビルドの再現性を担保できる。`npm` の内部キャッシュをコンテナ層で活用するため、ビルドコンテナの `node_modules` をボリュームとしてマウントする設定も検討すべきだ。

—

4. 伝説的エンジニアが教える「リリース事故」を未然に防ぐCLIハック

どれだけルールを定めても、ヒューマンエラーは起きる。これを防ぐには、`npm publish` を直接叩かせない運用を強制することだ。

独自自動化スクリプト (`scripts/publish-guard.sh`):

!/bin/bash
権限チェックとブランチガード
CURRENT_BRANCH=$(git rev-parse –abbrev-ref HEAD)
if [ “$CURRENT_BRANCH” != “main” ]; then
echo “❌ エラー: リリースはmainブランチからのみ可能です。”
exit 1
fi

依存関係の整合性チェック
npm audit –audit-level=high
if [ $? -ne 0 ]; then
echo “❌ エラー: セキュリティ脆弱性が検出されました。”
exit 1
fi

npm publish

このスクリプトを `package.json` の `scripts` に登録し、開発者には `npm run release` を叩かせる。さらに言えば、GitHub Actionsの `workflow_dispatch` でのみ `npm publish` が実行される権限設定をIAM/Tokenで制御し、ローカルからの直接公開を物理的に封印するのが、真に堅牢なDevOpsの姿である。

—

結論：ツールを「使わされる」側から「操る」側へ

`prepare` や `prepublishOnly` は単なるコマンドフックではない。それは、「あなたのコードが世界へ公開されるまでの品質門番」である。

`prepare` は、開発者が `npm install` した瞬間に常に最新の成果物を保証するための「自己修復装置」。
`prepublishOnly` は、人間の過ちを最後の最後で止めるための「最終防衛線」。

これらを理解し、CI/CDパイプラインという「工場のベルトコンベア」に適切に配置することで、あなたのチームはリリース作業から解放され、本来の「価値創造」に集中できるようになる。

次は、あなたのプロジェクトの `package.json` を開き、今日紹介した「防衛線」が正しく機能しているか確認してほしい。もし修正が必要なら、今すぐ手を動かそう。コードは嘘をつかない。設定した通りの品質でしか、世界には出ないのだから。