Last updated 12 January 2021

このドキュメントでは、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 の動作を制御することもできます。

​

キャッシュの動作

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

​

デフォルトの 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​ のソースコードを調べてください。