最終更新日 2023年05月18日(木)

このドキュメントでは、Node.js アプリケーションの認識と実行に関連した Heroku の一般的な動作について説明します。アプリケーションのデプロイ方法に関する詳しい説明は、「Heroku スターターガイド (Node.js)」 を参照してください。

アクティベーション

Heroku の Node.js buildpack が使用されるのは、アプリケーションのルートディレクトリに package.json​ ファイルがある場合だけです。

Node.js ランタイム

Node のバージョンは、GitHub によって一般に普及しているセマンティックバージョニング規約である semver​ に準拠します。semver では MAJOR.MINOR.PATCH​ 形式のバージョンスキームが使用されます。

• MAJOR​ は互換性のない API 変更を示します
• MINOR​ は下位互換性のある方法で追加される機能を示します
• PATCH​ は下位互換性のあるバグ修正を示します

サポートされているランタイム

Heroku では、現在の​バージョンの Node.js だけでなく、すべてのアクティブな LTS​ (長期サポート) バージョンがサポートされています。Heroku では、Node チームからの正式リリースの 24 時間以内に新規リリースがサポートされる予定です。次の Node.js のリリーススケジュールに示されているように、Heroku の現在サポートされている Node.js バージョンは 16.x​、18.x​、20.x​ です。

その他の使用可能なランタイム

Heroku は標準の Ubuntu Linux スタックに基づいているため、ほとんどの Node バージョン (>= 0.10.0​) をプラットフォームで実行できます。ただし、buildpack のテストおよびサポートは、アクティブな LTS および安定リリースに重点が置かれています。

Node.js バージョンの指定

常に、開発やテストで使用しているランタイムに一致する Node.js バージョンを指定します。ローカルのバージョンを検索するには、次のようにします。

$ node --version
v18.7.0

最初に、アプリケーションが heroku/nodejs​ buildpack を使用していることを確認します。

$ heroku buildpacks
=== issuetriage Buildpack URLs
1. heroku/nodejs

次に、package.json​ の engines​ セクションを使用して、Heroku で使用する Node.js のバージョンを指定します。'v’ を削除してバージョン番号のみを保存します。

{
  "name": "example-app",
  "description": "a really cool app",
  "version": "1.0.0",
  "engines": {
    "node": "18.x"
  }
}

Node から最新のパッチ更新を取得するために、パッチに x​ を使用することをお勧めします。また、マイナー範囲 (18.7​ など) または正確なバージョン (16.19.1​ など) を指定することもできます。

npm バージョンの指定

Node.js は npm にバンドルされているため、ほとんどの場合は npm バージョンを別途指定する必要はありません。ただし、ローカルで意図的に異なるバージョンの npm を使用している場合、Heroku で同じバージョンの npm を指定することができます。

{
  "name": "example-app",
  "description": "a really cool app",
  "version": "0.0.1",
  "engines": {
    "npm": "7.x"
  }
}

Yarn バージョンの指定

アプリケーションのルートに package.json​ と共に yarn.lock​ ファイルがある場合、Heroku では Yarn をダウンロードしてインストールし、これを使用して依存関係をインストールします。ローカルで使用しているバージョンを指定して、Heroku で同じバージョンが使用されるようにします。

{
  "name": "example-app",
  "description": "a really cool app",
  "version": "1.0.0",
  "engines": {
    "yarn": "1.x"
  }
}

ビルド動作

Node プロジェクトは Yarn パッケージマネージャ​または npm パッケージマネージャ​のいずれかを使用してビルドされます。

yarn.lock​ ファイルがプロジェクトのルートに検出された場合、依存関係のインストールとスクリプトの実行に Yarn が使用されます。それ以外の場合は、npm が使用されます。yarn.lock​ をプロジェクトにチェックインした場合に、Heroku でのビルドに npm を使用する場合は、yarn.lock​ を .slugignore​ ファイルに追加します。

パッケージのインストール

デフォルトでは、Heroku は package.json​ の dependencies​ および devDependencies​ に記載されているすべての依存関係をインストールします。

インストールおよびビルドステップ​を実行した後、 Heroku はアプリケーションをデプロイする前に、devDependencies​ に宣言されているパッケージを取り除きます。

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

npm install の使用

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

$ heroku config:set USE_NPM_INSTALL=true

npm install​ を使用する場合、Heroku キャッシュを使用​してビルドを高速化する必要があります。npm install​ を使用しない場合、先に進んでビルドキャッシュを無効化できます。

$ heroku config:set NODE_MODULES_CACHE=false

dependencies のみのインストール

次の環境変数​を設定することによって、dependencies​ のみをインストールするよう Heroku に指示することができます。

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

$ heroku config:set NPM_CONFIG_PRODUCTION=true YARN_PRODUCTION=true

プルーニングのスキップ

別の buildpack またはランタイムに devDependencies​ に宣言されたパッケージにアクセスする必要がある場合、使用されるパッケージマネージャーによって、以下のいずれかの環境変数​を設定してプルーニングステップをスキップできます。

• NPM_CONFIG_PRODUCTION=false​ (npm​ の場合)
• YARN_PRODUCTION=false​ (Yarn v1​ の場合)
• YARN2_SKIP_PRUNING=true​ (Yarn v2+​ の場合)

$ heroku config:set NPM_CONFIG_PRODUCTION=false YARN_PRODUCTION=false YARN2_SKIP_PRUNING=true

NODE_ENV は production ではない

デフォルトでは、NODE_ENV​ は production​ に設定されています。NODE_ENV​ が 他の値である場合、プルーニングステップはスキップされます。

$ git push heroku main
...
-----> Pruning devDependencies
       Skipping because NODE_ENV is 'test'
...

Yarn を使用するために生成された他のファイルと一緒に、作成されたすべての成果物を .yarn​ ファイルで git にチェックインします。

ビルドプロセスのカスタマイズ

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

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

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

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

Heroku 固有のビルドステップ

npm install​ および yarn install​ に標準的な 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."
}

環境変数

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

$ heroku config:set MY_CUSTOM_VALUE=foobar

ビルドフラグ

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

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

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

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

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

npm の設定

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

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

プライベート依存関係

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 には、ビルド間で永続するビルドキャッシュ​があります。このキャッシュは、npm、Yarn および bower からのキャッシュを保存するために使用されます。

必要に応じて、Node.js アプリのすべてのキャッシュを無効化できます。

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

カスタムキャッシュ

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

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

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

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

"cacheDirectories": ["data"]

ランタイムの動作

buildpack では、node​、npm​、および node_modules/.bin​ を PATH​ に指定するため、heroku run​ で実行したり、Procfile 内で直接使用したりできます。

$ cat Procfile
web: npm start

NODE_ENV​ 環境変数はデフォルトで ‘production’ に設定されますが、任意の文字列に設定できます。

$ heroku config:set NODE_ENV=staging

デフォルトの Web プロセスタイプ

最初に、Heroku はプロセスタイプを指定する Procfile​ を検索します。

ビルドプロセス中にアプリのルートディレクトリに Procfile​ が存在しない場合、package.json 内で指定できるスクリプトである npm start​ を実行することによって Web プロセスが開始されます。

"scripts": {
  "start": "node server.js"
}

アプリの構成で web​ 以外のプロセスのみを実行する場合、web​ を明示的にスケールダウンし、他のプロセスタイプをスケールアップする必要があります。たとえば、次のようになります。

$ heroku scale web=0 worker=1

警告

ビルドに失敗した場合、Node.js buildpack は Node アプリケーション内の一般的な問題を特定し、警告と共にベストプラクティスとなる推奨事項を提供します。Node.js のビルドの問題がある場合、この場所からデバッグを開始することをお勧めします。

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

アドオン

デフォルトでプロビジョニングされるアドオンはありません。 アプリ用のデータベースが必要な場合は、明示的に追加してください。

$ heroku addons:create heroku-postgresql

複数の buildpack による動作

Node.js buildpack を他の buildpack​ と一緒に使用するとき、後続の buildpack が使用するために、node​、npm​、および node_modules​ バイナリを PATH​ に自動的にエクスポートします。

理解を深める

Heroku Node.js buildpack はオープンソースです。buildpack の動作方法を技術的にさらに理解するには、github.com/heroku/heroku-buildpack-nodejs​ のソースコードを調べてください。