Specify dependencies in Node.js

A function is allowed to use external Node.js modules as well as local data. Dependencies in Node.js are managed with npm and expressed in a metadata file called package.json. The Cloud Functions Node.js runtimes support installing using npm, yarn, or pnpm.

To specify a dependency for your function, add it to your package.json file.

Note: If a package-lock.json, yarn.lock, or pnpm-lock.yaml file is found within your project, that lock file will be respected when dependencies are installed using npm ci, yarn install or pnpm install.

In this example, a dependency is listed in the package.json file:

{
  "dependencies": {
    "escape-html": "^1.0.3"
  }
}

The dependency is then imported in the function:

functions/helloworld/helloworldHttp/index.js

View on GitHub

const functions = require('@google-cloud/functions-framework');
const escapeHtml = require('escape-html');

/**
 * Responds to an HTTP request using data from the request body parsed according
 * to the "content-type" header.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
functions.http('helloHttp', (req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

Using npm to install Node.js modules locally

The easiest way to install a Node.js module locally is to use the npm install command in the folder containing your Cloud Function. For instance, the following command adds the uuid module:

npm install uuid

This combines two steps:

1. It marks the latest version of the module as a dependency in your package.json file. This is very important: Cloud Functions only installs modules that are declared in your package.json file.
2. It downloads the module into your node_modules directory. This lets you use the module when developing locally.

If you don't have npm installed on your machine, get npm.

Note: npm packages are available for a variety of Google Cloud products. See the list here.

Configuring deployment dependencies

You can install production dependencies for NPM, Yarn, or Pnpm:

NPM

When you deploy your function, Cloud Functions installs dependencies declared in the package.json file using the npm install command:

npm install --production

Yarn

In the Node.js 8 runtime and higher, if a yarn.lock file exists, Cloud Functions instead uses the yarn install command:

yarn install --production

Pnpm

In the Node.js 8 runtime and higher, if a pnpm-lock.yaml file exists, Cloud Functions instead uses the pnpm install command:

pnpm install

Note: Dependencies declared in subdirectories are not installed. If you are using a monorepo, you may want to execute a custom build script during deployment to install those dependencies.

Executing custom build steps during deployment

After you deploy, you can perform a custom build step during the function build process by adding a gcp-build script in your package.json file.

When this script is executed, the dependencies in the dependencies and devDependencies fields of your package.json file are available. After executing your custom build step, Cloud Functions removes and regenerates the node_modules folder by only installing the production dependencies declared in the dependencies field of your package.json file.

If there is no gcp-build script in package.json, Cloud Functions just installs production dependencies.

Using system packages

The Node.js runtime also includes a number of system packages in the execution environment. If your function uses a dependency that requires a package that is not listed, you can request a package.

Note: you can also deploy containerized versions of your Node.js Cloud Functions to Cloud Run using the Functions Framework.

Including local Node.js modules

You can also include local Node.js modules as part of your function. You can achieve this by declaring your module in package.json using the file: prefix. In the following example, mymodule refers to your module name and mymoduledir is the directory containing your module:

{
  "dependencies": {
    "mymodule": "file:mymoduledir"
  }
}

The code for this local module should be stored somewhere other than the node_modules folder within your function's root directory.

Note: if you deploy using the gcloud command-line tool, gcloud automatically creates a .gcloudignore file in your function's directory. By default, the node_modules folder is added to this .gcloudignore and is not uploaded as part of your deployment. You do not need to include the node_modules folder when you manually upload code as a .zip file—you can successfully deploy your function without the the node_modules folder.

Loading Node.js modules

Use the Node.js require() function to load any Node.js module you have installed. You can also use the require() function to import local files you deploy alongside your function.

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 v2 or higher 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 Cloud Functions 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 without generating additional credentials. For example:

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

This approach also works for the Yarn v1 package manager. If you're using Yarn v2 or higher, you only need to list the Artifact Registry repository in your .yarnrc.yml 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.

Note: If you're using any custom permissions (such as those necessary for VPC), make sure that you explicitly allow your functions to access the target private repository.

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. If your repository is hosted with 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 npm 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.