Building a Node.js application

Specifying versions of Node.js

The buildpacks project provides support for the Current and Active LTS releases of Node.js. Older releases of Node.js are available but may not be actively maintained by the project.

Using package.json

You can specify the Node.js version of your application during deployment by configuring the engines.node field in package.json. To configure the buildpack to use the latest version of Node.js v16 when deploying your app, you can use the following values in your package.json:

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

Using GOOGLE_NODEJS_VERSION

It is also possible to specify the Node.js version via the GOOGLE_NODEJS_VERSION environment variable. If both configurations are set, the GOOGLE_NODEJS_VERSION value takes precedence over the engines.node property. If no value is provided, then the most recent LTS version of Node.js is used

To configure the buildpack to use Node.js 16 when deploying your app:

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

You can also use a project.toml project descriptor to encode the environment variable alongside your project files. See instructions on building the application with environment variables.

Tips

  • engines.node field can take a semver constraint. The specific library we use for the Node.js buildpacks is Masterminds/semver
  • Avoid using greater than (>) specifiers in engines.node
  • When deploying the application into App Engine standard environment, the engines.node property should be compatible with the runtime specified in app.yaml
  • Additional documentation about the engines.node configuration option in package.json can be found in the official NPM documentation under the engines topic
  • When deploying a function onto Cloud Functions, the engines.node property should be compatible with the runtime used to deploy your function

Installing dependencies

Using NPM

  • NPM is the default package manager.
  • Whenever possible, use package-lock.json to improve cache performance.
  • By default only production dependencies are installed.
  • You can specify the npm version section using the engines.npm field in your package.json file.

Using Yarn

  • Yarn is used instead when you include the yarn.lock file in your project.
  • You can specify the yarn version to use in the engines.yarn field of your package.json file.
  • We support Yarn2 PnP mode if your project includes a .yarn/cache.

Using Pnpm

  • Pnpm is used instead when you include the pnpm-lock.yaml file in your project.
  • You can specify a version of pnpm in the engines.pnpm field of your package.json file.
  • For a working example, see the sample-node-pnpm app.

Using private modules

You can use a private npm module by providing settings for authenticating with the registry in a .npmrc file in the function's directory. If you're using Yarn version 2 or later as your package manager, this file is named .yarnrc.yml.

Private modules from Artifact Registry

An Artifact Registry Node.js package repository can host private modules for your function. When you deploy a Buildpacks function, the build process automatically generates Artifact Registry credentials for the Cloud Build service account. You only need to list the Artifact Registry repository in your .npmrc file when using NPM or Yarn version 1. For example, when using NPM or Yarn version 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

If you're using Yarn version 2 or later, you only need to list the Artifact Registry repository in your .yarnrc.yml file without additional credentials. For example:

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

Private modules from other repositories

The npm documentation explains how to create custom read-only access tokens. We discourage using the .npmrc file created in the home directory because it contains a read-write token. Write permissions are not required during deployment, and could pose a security risk.

Do not include the .npmrc file if you're not using private repositories, as it can increase the deployment time for your functions.

File format

If you're using an .npmrc file to set a custom auth token, it should include the line shown below.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Replace:

  • REGISTRY_DOMAIN: the domain name of your private npm registry. For example if your repository host is npmjs.org, set this field to registry.npmjs.org.

  • AUTH_TOKEN: the authorization token for your npm registry. This can either be the literal text value of the token or the text string ${NPM_TOKEN}, which the npm command replaces with the actual token value from the environment.

    You can set the $NPM_TOKEN environment variable with the --set-build-env-vars argument to your gcloud functions deploy command. See the NPM tutorial on private modules for more details of the NPM auth token.

Executing custom build steps during deployment

By default, npm run build is run if a script is specified in your package.json file. However, you can instead specify custom build steps to override the default behavior and run only the scripts that you want during the build. You can control the build steps by using either the GOOGLE_NODE_RUN_SCRIPTS environment variable or gcp-build in your package.json file.

You can only use one method. Note that the GOOGLE_NODE_RUN_SCRIPTS environment variable takes precedence and overrides anything that is specified for gcp-build in your package.json.

By default, when you configure custom build steps, both the dependencies and devDependencies in your package.json file are installed first before any scripts or commands are executed. To override the default behavior, you can use the NODE_ENV environment variable.

Using GOOGLE_NODE_RUN_SCRIPTS

You can pass the GOOGLE_NODE_RUN_SCRIPTS environment variable to the build to control what scripts run. You can specify one or more scripts, or instead pass an empty environment variable to prevent the default behavior from running, like GOOGLE_NODE_RUN_SCRIPTS=. For complete details, see Environment variables.

Using package.json

Adding gcp-build in your package.json file only runs npm run gcp-build, meaning that it overrides the default behavior. You can specify one or more commands, or instead specify an empty string to prevent any command from running, like "gcp-build":"".

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

Application entrypoint

The Node.js buildpack will execute the command specified in the scripts.start field of your package.json. If scripts.start is not set, the buildpack will run npm start.

We recommend using a Procfile because it takes npm or yarn out of the path.

Environment variables

You can set environment variables to configure builds of your container image.

The Node.js buildpack supports the following environment variables to customize your container.

NPM_CONFIG_<key>

See documentation.

Example: NPM_CONFIG_FLAG=value passes -flag=value to npm commands.

NODE_ENV

Specifies the development environment during the build; set for npm install.

Example: NODE_ENV=development installs both the dependencies and devDependencies specified in package.json.

GOOGLE_NODE_RUN_SCRIPTS

Specifies an ordered list of npm scripts from package.json to run after installing dependencies. The list must be comma-separated and runs in the order that you list each script.

When you specify GOOGLE_NODE_RUN_SCRIPTS, only the scripts that you list are run. For example, if you want to prevent the default npm run build from running, you specify the environment variable without a value.

Examples:

  • GOOGLE_NODE_RUN_SCRIPTS=lint,build runs npm run lint and then npm run build.
  • GOOGLE_NODE_RUN_SCRIPTS= runs no scripts.