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.
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:
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:
- 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 yourpackage.json
file. - 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.
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
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.
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.
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.
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 toregistry.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}
, whichnpm
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 yourgcloud functions deploy
command. See the NPM tutorial on private modules for more details of the NPM auth token.