Heroku の Node.js サポート
この記事の英語版に更新があります。ご覧の翻訳には含まれていない変更点があるかもしれません。
最終更新日 2019年04月30日(火)
Table of Contents
このドキュメントでは、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 (長期サポート) バージョンがサポートされています。
現在サポートされているバージョンは、8.x
、10.x
、および 12.x
です。
使用可能なその他のランタイム
Heroku は標準の Ubuntu Linux スタックに基づいているため、ほとんどの Node バージョン (>= 0.10.0) をプラットフォームで実行できます。ただし、buildpack のテストおよびサポートは、アクティブな LTS および安定リリースに重点が置かれています。
Node.js バージョンの指定
開発およびテストで使用するランタイムに合った Node.js バージョンを常に指定する必要があります。ローカルのバージョンを検索するには、次のようにします。
$ node --version
v10.3.0
最初に、アプリケーションが heroku/nodejs
buildpack を使用していることを確認します。
$ heroku buildpacks
=== issuetriage Buildpack URLs
1. heroku/nodejs
次に、package.json
の engines
セクションを使用して、Heroku で使用する Node.js のバージョンを指定します。'v’ を削除してバージョン番号のみを保存します。
{
"name": "myapp",
"description": "a really cool app",
"version": "1.0.0",
"engines": {
"node": "10.3.0"
}
}
semver の範囲も指定できます (10.x
など)。
バージョンを指定しない場合、最新の長期サポートリリースが使用されます。
npm バージョンの指定
Node.js は npm にバンドルされているため、ほとんどの場合は npm バージョンを別途指定する必要はありません。ただし、ローカルで意図的に異なるバージョンの npm を使用している場合、Heroku で同じバージョンの npm を指定することができます。
{
"name": "myapp",
"description": "a really cool app",
"version": "0.0.1",
"engines": {
"npm": "6.x"
}
}
Yarn バージョンの指定
アプリケーションのルートで package.json
と一緒に yarn.lock
ファイルが見つかった場合、Heroku は Yarn をダウンロードしてインストールし、これを使用して依存関係をインストールします。ただし、ローカルで使用するバージョンを指定して、Heroku で同じバージョンが使用できるようにする必要があります。
{
"name": "myapp",
"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
に宣言されているパッケージを取り除きます。
dependencies
のみのインストール
環境変数
NPM_CONFIG_PRODUCTION=true
または YARN_PRODUCTION=true
を設定することによって、dependencies
のみをインストールするよう Heroku に指示することができます。
$ heroku config:set NPM_CONFIG_PRODUCTION=true YARN_PRODUCTION=true
プルーニングのスキップ
別の buildpack またはランタイムに
devDependencies
に宣言されたパッケージにアクセスする必要がある場合、NPM_CONFIG_PRODUCTION=false
または
YARN_PRODUCTION=false
を設定してプルーニングステップをスキップできます。
$ heroku config:set NPM_CONFIG_PRODUCTION=false YARN_PRODUCTION=false
NODE_ENV
は production
ではない
デフォルトでは、NODE_ENV
は production
に設定されています。NODE_ENV
が
他の値である場合、プルーニングステップはスキップされます。
$ git push heroku master
...
-----> Pruning devDependencies
Skipping because NODE_ENV is 'test'
...
ビルドプロセスのカスタマイズ
デプロイ中に実行するビルドステップがアプリにある場合、package.json 内で build
スクリプトを使用できます。
"scripts": {
"start": "node index.js",
"build": "webpack"
}
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 固有のビルドステップ
Node.js に標準的な preinstall
および postinstall
スクリプトがある場合、Heroku のビルドの前のみまたは後のみにスクリプトを実行することが必要な場合もあります。たとえば、Heroku が依存関係をインストールする前に、npm、git、または ssh の設定が必要な場合もあります。または、依存関係がインストールされた後に、本番アセットのビルドが必要な場合もあります。
Heroku 固有のアクションの場合、heroku-prebuild
および heroku-postbuild
スクリプトを使用します。
"scripts": {
"heroku-prebuild": "echo This runs before Heroku installs your dependencies.",
"heroku-postbuild": "echo This runs afterwards."
}
環境変数
アプリの 環境はビルド中に使用可能で、環境変数の値に基づいてビルド動作を調整できます。たとえば次のようになります。
$ heroku config:set MY_CUSTOM_VALUE=foobar
npm の設定
npm
は、NPM_CONFIG
で始まるあらゆる環境変数から設定を読み取ります。
また、プロジェクトのルートの .npmrc
ファイル経由で npm の動作を制御することもできます。
NPM_CONFIG_PRODUCTION が true の場合、npm は NODE_ENV が ‘production’ であるサブシェル内のすべてのスクリプトを自動実行します。
キャッシュの動作
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 master
カスタムキャッシュ
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
通常の場合、NODE_ENV は ‘production’ です。いくつかのモジュール (express を含む) では、NODE_ENVに基づいてそれらの動作を暗黙的に変更します。
デフォルトの 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 のソースコードを調べてください。