最終更新日 2025年03月17日(月)

Heroku の Node.js buildpack​ は、アプリがクラシック​ buildpack を使用するか、Cloud Native Buildpack (CNB)​ を使用するかによってビルド動作が異なります。

この記事では、Heroku のクラシック Node.js buildpack​ を使用したアプリのビルド動作と、ビルドプロセスをカスタマイズする方法について説明します。Node.js アプリケーションは、npm​、pnpm​、または Yarn​ のパッケージマネージャーを使用する場合、同じビルドプロセスをたどります。

主な手順

ビルドプロセスの主な手順は次のとおりです。

1. 依存関係をインストールする
2. 不要な依存関係を削除する
3. 依存関係をキャッシュする

デフォルトでは、Heroku は package.json​ の dependencies​ および devDependencies​ に定義されているすべての依存関係をインストールします。dependencies のみをインストール​するように選択することもできます。

Heroku では、ロックファイル (package-lock.json​、pnpm-lock.yaml​ または yarn.lock​) を使用して、期待される依存関係ツリーをインストールします。これらのファイルを Git にチェックインして、環境全体の依存関係バージョンを同じにしてください。npm​を使用する場合、Heroku では npm ci​​ を使用してビルド環境を設定します。npm ci​ の代わりに npm install​ を選択することもできます。

インストールを実行した後、Heroku はアプリケーションをデプロイする前に、devDependencies​ に宣言されている不要なパッケージを削除します。プルーニングをスキップ​することもできます。

Heroku では、ビルドをまたいで持続するビルドキャッシュ​を維持します。このキャッシュには、npm​、yarn​、pnpm​、bower​ のモジュールが保存されます。Heroku はデフォルトで、node_modules​ および bower_components​ ディレクトリを保存します。キャッシュされる場所をカスタマイズ​したり、完全にキャッシュを無効化​したりすることができます。

デプロイ中に実行するビルドステップがアプリにある場合、package.json​ で build​ スクリプトを使用​できます。依存関係をインストールする前など、ほかの Heroku ビルドステップの前後に​スクリプトを実行することもできます。

ビルドの失敗

ビルドに失敗した場合、Node.js buildpack は Node アプリケーション内の一般的な問題を特定し、警告と共にベストプラクティスとなる推奨事項を提供します。

また、Node.js の一般的な問題のトラブルシューティング​に役立つドキュメントもあります。

環境変数

ビルド中もアプリの環境設定は使用可能なため、環境変数の値に基づいてビルド動作を調整できます。たとえば、次のようになります。

$ heroku config:set MY_CUSTOM_VALUE=foobar

npm を設定する

npm​ は、NPM_CONFIG​ で始まるあらゆる環境変数から設定を読み取ります。

また、プロジェクトのルートの .npmrc​ ファイル経由で npm​ の動作を制御することもできます。

ビルドプロセスにビルドステップを追加する

デプロイ中に実行するビルドステップがアプリにある場合、package.json​ で build​ スクリプトを使用できます。

"scripts": {
  "start": "node index.js",
  "build": "webpack"
}

Heroku 用のカスタマイズが必要な build​ スクリプトが package.json​ にある場合、build​ スクリプトの代わりに実行される heroku-postbuild​ スクリプトを定義します。

"scripts": {
  "start": "node index.js",
  "build": "ng build",
  "heroku-postbuild": "ng build --prod" // this command will run on Heroku
}

Heroku 固有のビルドステップの前後にステップを追加する

各パッケージマネージャーは標準の preinstall​ および postinstall​ スクリプトをサポートしていますが、Heroku のほかのビルドステップの前後にのみスクリプトを実行することもできます。たとえば、Heroku が依存関係をインストールする前に npm​、git​、または ssh​ を設定する場合や、依存関係がインストールされた後に本番アセットをビルドする場合です。

Heroku 固有のアクションの場合、heroku-prebuild​、heroku-postbuild​、および heroku-cleanup​ スクリプトを使用します。

"scripts": {
  "heroku-prebuild": "echo This runs before Heroku installs dependencies.",
  "heroku-postbuild": "echo This runs after Heroku installs dependencies, but before Heroku prunes and caches dependencies.",
  "heroku-cleanup": "echo This runs after Heroku prunes and caches dependencies."
}

ビルドフラグ

アプリでビルドステップを実行する場合は、開発および本番用に使用されるようにしてください。そうでない場合は、ビルドフラグ環境変数を使用して、ビルドスクリプトのフラグを設定します。たとえば、ビルドステップが以下であるとします。

"scripts": {
  "build": "ng build"
}

NODE_BUILD_FLAGS​ 環境変数を設定できます。

$ heroku config:set NODE_BUILD_FLAGS="--prod"

この変数を設定すると、ビルドステップでは ng build --prod​ を代わりに実行します。

dependencies のみをインストールする

次の環境変数​を設定することにより、devDependencies​ もインストールするのではなく、dependencies​ のみをインストールするよう Heroku に指示できます。

• NPM_CONFIG_PRODUCTION=true​ (npm​ の場合)
• YARN_PRODUCTION=true​ (Yarn v1​ の場合)

$ heroku config:set NPM_CONFIG_PRODUCTION=true YARN_PRODUCTION=true

npm ci の代わりに npm install を使用する

npm ci​ ではなく npm install​ を使用してビルド環境を作成するには、USE_NPM_INSTALL​ 環境変数を使用してbuildpack に認識させることができます。次のように実行します。

$ heroku config:set USE_NPM_INSTALL=true

npm install​ を使用する場合は、Heroku キャッシュ​を使用してビルド時間を短縮します。npm install​ を使用しない場合は、ビルドキャッシュを無効化​します。

プルーニングのスキップ

ビルドプロセスや対象となる環境によっては、devDependencies​ に宣言されたパッケージを保持しておく必要があります。プルーニングステップは、対象の NODE_ENV​ によって、またはこのステップをオプトアウトする環境変数​が設定されている場合にスキップできます。

npm を使用してプルーニングをスキップする

$ heroku config:set NPM_CONFIG_PRODUCTION=false

pnpm を使用してプルーニングをスキップする

$ heroku config:set PNPM_SKIP_PRUNING=true

Yarn v1 を使用してプルーニングをスキップする

$ heroku config:set YARN_PRODUCTION=false

Yarn v2 以上を使用してプルーニングをスキップする

$ heroku config:set YARN2_SKIP_PRUNING=true

カスタムキャッシュ

Heroku はデフォルトで、node_modules​ および bower_components​ ディレクトリを保存します。トップレベルの package.json に cacheDirectories​ 配列を指定することで、これらのデフォルトをオーバーライドできます。

たとえば、クライアントおよびサーバーのサブディレクトリ内でビルドする場合は、次のようになります。

"cacheDirectories": ["client/node_modules", "server/node_modules"]

また、アプリで何らかの種類の大きいディレクトリが必要で、data/dictionary.txt に保管される場合は、次のようになります。

"cacheDirectories": ["data"]

キャッシュを無効化する

NODE_MODULES_CACHE​ の環境設定を設定して、Node.js アプリのすべてのキャッシュ​を無効化できます。

$ heroku config:set NODE_MODULES_CACHE=false
$ git commit -am 'disable node_modules cache' --allow-empty
$ git push heroku main

プライベート依存関係を使用する

NPM Enterprise や Gemfury などのプライベート依存関係ソースからプルする場合、プロジェクトはアクセストークンを使用して代替レジストリを設定する必要があります。

プライベートレジストリ URL を .npmrc​ に追加します。この場合、パブリックであっても NPM のレジストリを指定して、プライベート用に使用されるスコープでこのスコープを置き換えます。次に、認証トークンを使用してポイントするレジストリ URL を追加します。

echo "@scope:registry=https://registry.npmjs.org" >> .npmrc
echo -e "//registry.npmjs.org/:_authToken=\${NPM_TOKEN}" >> .npmrc

.npmrc​ は次のようになります。

@scope:registry=https://registry.npmjs.org
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

NPM_TOKEN​ が Heroku 設定に追加され、ビルドでトークンにアクセスしてプライベートパッケージをインストールできることを確認します。

heroku config:set NPM_TOKEN=PRIVATE_NPM_TOKEN

バイナリダウンロードのカスタマイズ

環境変数​ NODE_BINARY_URL​ および YARN_BINARY_URL​ をカスタム URL に設定することで、Node と yarn のバイナリのダウンロード先をカスタマイズできます。次に例を示します。

$ heroku config:set NODE_BINARY_URL=https://s3.amazonaws.com/your-custom-binary-url/

その他の資料

• Heroku の Node.js サポートリファレンス
• Heroku での Node.js の動作
• slug コンパイラ