Node.js アプリケーションの構築

Node.js のバージョンの指定

Buildpack プロジェクトは、Node.js の現在のリリースとアクティブな LTS リリースをサポートしています。古いリリースの Node.js も使用できますが、プロジェクトで積極的にメンテナンスされていない可能性があります。

package.json の使用

デプロイ時にアプリケーションで使用する Node.js のバージョンを指定するには、package.json の engines.node フィールドを構成します。アプリをデプロイするときに最新バージョンの Node.js v16 を使用するように Buildpack を構成するには、package.json で次の値を使用します。

"engines": {
  "node": "16.x.x"
}

GOOGLE_NODEJS_VERSION の使用

GOOGLE_NODEJS_VERSION 環境変数を使用して Node.js のバージョンを指定することもできます。両方が構成されている場合、GOOGLE_NODEJS_VERSION 値が engines.node プロパティよりも優先されます。値を指定しないと、Node.js の最新の LTS バージョンが使用されます。

アプリのデプロイ時に Node.js 16 を使用するように Buildpack を構成するには:

pack build --builder=gcr.io/buildpacks/builder \
   sample-functions-framework-node \
   --env GOOGLE_NODEJS_VERSION=16.x.x

project.toml プロジェクト記述子を使用して、プロジェクト ファイルとともに環境変数をエンコードすることもできます。環境変数を使用してアプリケーションを構築するの手順をご覧ください。

ヒント

  • engines.node フィールドに semver の制約を指定できます。Node.js Buildpack に使用する特定のライブラリは Masterminds/semver です
  • engines.node では、より大きい（>）指定子を使用しないでください。
  • アプリケーションを App Engine スタンダード環境にデプロイする場合、engines.node プロパティは app.yaml で指定されたランタイムと互換性を持つ必要があります。
  • package.json の engines.node 構成オプションに関する追加ドキュメントが公式の NPM ドキュメントにあります。詳しくは、エンジンのトピックをご覧ください。
  • 関数を Cloud Functions にデプロイする場合、engines.node プロパティは、関数のデプロイに使用するランタイムと互換性を持つ必要があります。

依存関係のインストール

npm を使用する場合

  • npm はデフォルトのパッケージ管理システムです。
  • キャッシュのパフォーマンスを向上させるため、可能な限り package-lock.json を使用してください。
  • デフォルトでは、本番環境の依存関係のみがインストールされます。
  • npm バージョンのセクションは、package.json ファイルの engines.npm フィールドで指定できます。

yarn を使用する場合

  • yarn を使用するには、プロジェクトに yarn.lock ファイルを含めます。
  • package.json ファイルの engines.yarn フィールドに、使用する yarn のバージョンを指定できます。
  • プロジェクトに .yarn/cache が含まれている場合は、Yarn2 PnP モードがサポートされます。

pnpm を使用する場合

  • pnpm を使用するには、プロジェクトに pnpm-lock.yaml ファイルを含めます。
  • package.json ファイルの engines.pnpm フィールドで、pnpm のバージョンを指定できます。
  • 実際の例については、sample-node-pnpm アプリをご覧ください。

非公開モジュールの使用

非公開の npm モジュールを使用するには、関数のディレクトリにある .npmrc ファイルに、レジストリを認証するための設定を記述します。Yarn バージョン 2 以降をパッケージ マネージャーとして使用している場合、このファイルの名前は .yarnrc.yml です。

Artifact Registry の非公開モジュール

Artifact Registry Node.js パッケージ リポジトリは、関数の非公開モジュールをホストできます。Buildpack の関数をデプロイすると、ビルドプロセスにより、Cloud Build サービス アカウント用の Artifact Registry 認証情報が自動的に生成されます。NPM または Yarn バージョン 1 を使用している場合、必要な操作は、.npmrc ファイルに Artifact Registry リポジトリのリストを記述するだけです。たとえば、NPM または Yarn のバージョン 1 を使用している場合は、次のようにします。

@SCOPE:registry=https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
//REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME:always-auth=true

Yarn バージョン 2 以降を使用している場合、必要な操作は、追加の認証情報なしで .yarnrc.yml ファイルに Artifact Registry リポジトリのリストを記述するだけです。次に例を示します。

npmScopes:
  SCOPE:
    npmRegistryServer: https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
    npmAlwaysAuth: true

他のリポジトリの非公開モジュール

npm のドキュメントでは、カスタムの読み取り専用アクセス トークンを作成する方法について説明しています。.npmrc ファイルには読み取り / 書き込みトークンが含まれているため、ホーム ディレクトリにこのファイルを作成して使用することは避けてください。デプロイ時に書き込み権限は必要なく、セキュリティ上のリスクが発生する可能性があります。

非公開リポジトリを使用していない場合は .npmrc ファイルを追加しないでください。追加すると、関数のデプロイ時間が長くなる可能性があります。

ファイル形式

.npmrc ファイルを使用してカスタム認証トークンを設定する場合は、以下の行を含める必要があります。

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

次のように置き換えます。

  • REGISTRY_DOMAIN: プライベート npm レジストリのドメイン名。たとえば、リポジトリ ホストが npmjs.org の場合、このフィールドを registry.npmjs.org に設定します。

  • AUTH_TOKEN: npm レジストリの認証トークン。トークンのリテラル テキスト値か、npm コマンドで環境の実際のトークン値に置き換えられるテキスト文字列 ${NPM_TOKEN} のいずれかになります。

    $NPM_TOKEN 環境変数と --set-build-env-vars 引数を gcloud functions deploy コマンドに設定できます。NPM 認証トークンについて詳しくは、プライベート モジュールに関する NPM のチュートリアルをご覧ください。

デプロイ時にカスタムビルド ステップを実行する

デフォルトでは、package.json ファイルでスクリプトを指定すると、npm run build が実行されます。代わりに、カスタム ビルドステップを指定して、デフォルトの動作をオーバーライドし、ビルド時に必要なスクリプトのみを実行することもできます。ビルドステップを制御するには、package.json ファイルで GOOGLE_NODE_RUN_SCRIPTS 環境変数または gcp-build を使用します。

使用できるメソッドは 1 つのみです。GOOGLE_NODE_RUN_SCRIPTS 環境変数は優先され、package.json の gcp-build に対する指定をオーバーライドします。

デフォルトでは、カスタム ビルドステップを構成すると、スクリプトまたはコマンドが実行される前に、package.json ファイル内の dependencies と devDependencies の両方がインストールされます。デフォルトの動作をオーバーライドするには、NODE_ENV 環境変数を使用します。

GOOGLE_NODE_RUN_SCRIPTS の使用

GOOGLE_NODE_RUN_SCRIPTS 環境変数をビルドに渡して、実行するスクリプトを制御できます。1 つ以上のスクリプトを指定するか、空の環境変数を渡して、GOOGLE_NODE_RUN_SCRIPTS= などのデフォルトの動作が実行されないようにします。詳細については、環境変数をご覧ください。

package.json の使用

package.json ファイルに gcp-build を追加すると、npm run gcp-build のみが実行されます。つまり、デフォルトの動作がオーバーライドされます。1 つ以上のコマンドを指定するか、空の文字列を指定して、"gcp-build":"" などのコマンドが実行されないようにすることができます。

"scripts": {
  ...
  "gcp-build": "npm run lint && npm run build"
  ...
}

アプリケーション エントリポイント

Node.js Buildpack は、package.json の scripts.start フィールドで指定されたコマンドを実行します。scripts.start が設定されていない場合、Buildpack は npm start を実行します。

パスから npm または yarn を取得できるので Procfile の使用をおすすめします。

環境変数

コンテナ イメージのビルドを構成するための環境変数を設定できます。

Node.js Buildpack は、コンテナをカスタマイズするための次の環境変数をサポートしています。

NPM_CONFIG_<key>

ドキュメントをご覧ください。

例: NPM_CONFIG_FLAG=value は -flag=value を npm コマンドに渡します。

NODE_ENV

ビルド中の開発環境を指定し npm install に設定します。

例: NODE_ENV=development は、package.json で指定された dependencies と devDependencies の両方をインストールします。

GOOGLE_NODE_RUN_SCRIPTS

依存関係のインストール後に実行する package.json の npm スクリプトの順序付きリストを指定します。これはカンマ区切りのリストで、リスト内の順番に従って各スクリプトが実行されます。

GOOGLE_NODE_RUN_SCRIPTS を指定すると、リストしたスクリプトのみが実行されます。たとえば、デフォルトの npm run build が実行されないようにするには、値を指定せずに環境変数を指定します。

例:

  • GOOGLE_NODE_RUN_SCRIPTS=lint,build は npm run lint を実行し、次に npm run build を実行します。
  • GOOGLE_NODE_RUN_SCRIPTS= はスクリプトを実行しません。