Handling dependencies

A Cloud Functions function can use external modules and local dependencies. How you specify and manage dependencies depends on your runtime language.

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.

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:

const onRequest = require("firebase-functions/https");
const escapeHtml = require("escape-html");

// Return a greeting with the input HTML-escaped.
exports.hello = onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || "World")}!`);
});

import { onRequest } from "firebase-functions/https";
import * as escapeHtml from "escape-html";

// Return a greeting with the input HTML-escaped.
export let hello = onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || "World")}!`);
});

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.

Additional steps for TypeScript

TypeScript helps you most when you use libraries that have type information. This lets TypeScript catch syntax errors and lets editors give you better autocomplete suggestions. Some libraries, like firebase-admin and firebase-functions, ship with TypeScript definitions included.

Many libraries do not provide their own TypeScript definition. The DefinitelyTyped project provides community-maintained definitions for the most popular node libraries. DefinitelyTyped publishes these definitions under the same NPM package name, but inside the "@types" organization. For example, you can install the type information for the uuid library with the following:

npm install @types/uuid

As you become more familiar with TypeScript, you might find yourself combining both installs:

npm install uuid @types/uuid

Type dependencies should be the same kind as the library dependency. For example, you should not save uuid as a normal dependency and @types/uuid as a dev dependency or peer dependency.

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.

If you are writing functions in TypeScript, use the import statement in the same way to load any Node.js module you have installed.

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 Google 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.

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.

Python

There are two ways to specify dependencies for Cloud Functions written in Python: using the pip package manager's requirements.txt file or packaging local dependencies alongside your function.

Dependency specification using the Pipfile/Pipfile.lock standard is not supported. Your project should not include these files.

Specifying dependencies with pip

Dependencies in Python are managed with pip and expressed in a metadata file called requirements.txt. This file must be in the same directory as the main.py file that contains your function code.

When you deploy or redeploy your function, Cloud Functions uses pip to download and install the latest version of your dependencies as declared in the requirements.txt file. The requirements.txt file contains one line per package. Each line contains the package name, and optionally, the requested version. For more details, see the requirements.txt reference.

To prevent your build from being affected by dependency version changes, consider pinning your dependency packages to a specific version.

The following is an example requirements.txt file:

functions-framework
requests==2.20.0
numpy

Packaging local dependencies

You can also package and deploy dependencies alongside your function. This approach is useful if your dependency is not available via the pip package manager or if your Cloud Functions environment's internet access is restricted.

For example, you might use a directory structure such as the following:

myfunction/
├── main.py
└── localpackage/
    ├── __init__.py
    └── script.py

You can then import the code as usual from localpackage using the following import statement.

# Code in main.py
from localpackage import script

Note that this approach will not run any setup.py files. Packages with those files can still be bundled, but may not run correctly on Cloud Functions.