The Node.js runtime is the software stack responsible for installing your application code and dependencies, and then running that application in the flexible environment.
Version
18
and later are built using buildpacks which enables you to choose an operating system. To use these new runtimes, you must specify additional settings in yourapp.yaml
file.Version
16
and earlier are built using Docker.The default Node.js engine uses the latest LTS release.
Node.js 20 runs on Ubuntu 22.
For other supported Node.js versions, and the corresponding Ubuntu version for your Node.js version, see the Runtime support schedule.
Package manager
During deployment, the runtime uses either the npm, or yarn, or Pnpm package manager to install dependencies and start the application. The package manager is set with the following logic:
- The default package manager is
npm
. - If a
yarn.lock
file is present in your application's root directory, the runtime instead uses theyarn
package manager. - For only Node.js runtimes version 18 and version 20, if a
pnpm-lock.yaml
file is present in your application's root directory, the runtime instead uses thePnpm
package manager. - If both a
package-lock.json
, andyarn.lock
orpnpm-lock.yaml
exist, your deployment will fail with an error. If you need thepackage-lock.json
file, you must specify the other package manager files in theskip_files
section of yourapp.yaml
file to resolve which package manager to use.
Choose a Node.js version
New runtime versions
For Node.js runtime version 18 and later, you must include the
runtime_config
and operating_system
settings in your
app.yaml
file
to specify an operating system.
To use the new runtimes, you must install gcloud CLI
version 420.0.0 or later.
You can update your CLI tooling by running the
gcloud components update
command.
To view your installed version, you can run the
gcloud version
command.
Optionally, specify a version by:
Adding the
runtime_version
setting in yourapp.yaml
file. By default, the latest Node.js version is used if theruntime_version
setting is not specified. For example,- To specify Node.js 20 on Ubuntu 22:
runtime: nodejs env: flex runtime_config: operating_system: "ubuntu22" runtime_version: "20"
- To specify the latest supported Node.js version on Ubuntu 22:
runtime: nodejs env: flex runtime_config: operating_system: "ubuntu22"
Including any Node.js version in your application's
package.json
file using theengines
field. Note that when you use theengines
field to specify a version, theruntime_version
setting takes precedence. To prevent unexpected breakages, it is recommended that you specify a Node.js version in theengines
field. For example,{ "engines": { "node": "20.x" } }
The
engines.node
property can be a semver range. If you specify this, the runtime downloads and installs the latest version of Node.js that matches the semver range. If no match is found, the application will fail to deploy and the runtime will return an error message.
Previous runtime versions
For Node.js runtime version 16 and earlier, specify a version in your
application's package.json
file using the engines
field.
The following example configures the runtime to use the latest Node 9 release.
{
"engines": {
"node": "9.x"
}
}
The engines.node
property can be a semver range. If you specify
this, the runtime downloads and installs the latest version of Node.js that
matches the semver range. If no match is found, the application will fail to
deploy and the runtime will return an error message.
Package manager version
The runtime image aims to use the latest yarn
release and the release of
npm
that is available in the latest Node.js LTS release.
You can specify a different package manager version to use in your application's
package.json
file by using the engines
field. In this
case, the runtime will ensure that the package manager used for the deployment
has a version that matches the specification listed in the
engines
field.
If both a yarn
and npm
version specification is
given, only the package manager that is used for the deployment will be
updated if needed. This saves deployment time by not installing a custom
version of a package manager if it is not actually being used to deploy your
application.
The following example configures the runtime to use a custom version of npm
:
{
"engines": {
"npm": "5.x"
}
}
The next example configures the runtime to use a custom version of yarn
:
{
"engines": {
"yarn": ">=1.0.0 <2.0.0"
}
}
The engines.npm
and engines.yarn
properties can both be a
semver range.
Dependencies
During deployment, the runtime will use either the npm or yarn
package manager to install dependencies by running npm install
or
yarn install
. See the Package Manager section for more
information on how the runtime selects the package manager to use.
Also, for more information about managing Node.js packages on Google App Engine, see Using Node.js Libraries.
To enable the use of Node.js packages that require native extensions, the following Ubuntu packages are pre-installed in the Docker image.
build-essential
ca-certificates
curl
git
imagemagick
libkrb5-dev
netbase
python
If your application requires additional operating-system-level dependencies, you will need to use a custom runtime based on this runtime to install the appropriate packages.
Application startup
The runtime starts your application by using npm start
, which uses
the command specified in package.json
. For example:
"scripts": {
"start": "node app.js"
}
Your start script should start a web server that responds to HTTP requests on
the port specified by the PORT
environment variable, typically 8080.
Extending the runtime
You can use custom runtimes to add
additional functionality to a Node.js app running in the App Engine flexible environment. To configure
a custom runtime, replace the following line in your app.yaml
file:
runtime: nodejs
with this line:
runtime: custom
You must also add Dockerfile
and .dockerignore
files in the same directory
that contains the app.yaml
file.
Visit the Custom runtimes documentation to learn how to define a Dockerfile in a custom runtime.
HTTPS and forwarding proxies
App Engine terminates the HTTPS connection at the load balancer and forwards the
request to your application. Some applications need to determine the original
request IP and protocol. The user's IP address is available in the standard
X-Forwarded-For
header. Applications that require this information should
configure their web framework to trust the proxy.
With Express.js, use the trust proxy
setting:
app.set('trust proxy', true);
For information on enforcing HTTPS connections, see How Requests are Handled.
Environment variables
The following environment variables are set by the runtime environment:
Environment variable | Description |
---|---|
GAE_INSTANCE |
The name of the current instance. |
GAE_MEMORY_MB |
The amount of memory available to the application process. |
GAE_SERVICE |
The service name specified in your application's app.yaml
file, or if no service name is specified, it is set to
default .
|
GAE_VERSION |
The version label of the current application. |
GOOGLE_CLOUD_PROJECT |
The Project ID associated with your application, which is visible in the Google Cloud console |
NODE_ENV |
When your app is deployed, the value is production . |
PORT |
The port that will receive HTTP requests. Set to 8080 .
|
You can set additional environment variables with
app.yaml
.
Metadata server
Each instance of your application can use the Compute Engine metadata server to query information about the instance, including its host name, external IP address, instance ID, custom metadata, and service account information. App Engine does not allow you to set custom metadata for each instance, but you can set project-wide custom metadata and read it from your App Engine and Compute Engine instances.
This example function uses the metadata server to get the external IP address
of the instance for Node.js runtime version 16 and earlier, and version
18 and later. Note that
you must update your app.yaml
to use the new version. See Node.js runtime
for more information about using newer versions.