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 escapeHtml = require('escape-html');
// Return a greeting with the input HTML-escaped.
exports.hello = functions.https.onRequest((req, res) => {
res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});
import * as escapeHtml from 'escape-html';
// Return a greeting with the input HTML-escaped.
export let hello = functions.https.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.
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 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.
Build your function with vendored dependencies
Vendored dependencies are those whose source is included directly in your source code package and rebuilt alongside your own code. You create vendored Node.js dependencies and skip installing them during deployment by using the GOOGLE_VENDOR_NPM_DEPENDENCIES build environment variable.
Prerequisites for vendored dependencies
Ensure that you have a working function with all the dependencies that you want to vendor defined in your
package.json
file.Install these dependencies locally by running
npm install
Remove
node_modules
from the .gcloudignore file in your working directory.Deploy the function, ensuring that your local Node.js version is the same as the one you specify during deployment.
Deploy your function and the vendored dependencies with the following command:
gcloud functions deploy
FUNCTION_NAME \ --runtimeRUNTIME_NAME \ --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=trueReplace:
- FUNCTION_NAME: the name of the Cloud Functions function you're deploying
- RUNTIME_NAME: the name of the Node.js runtime to run your deployed function under. This must be the same Node.js version as you've used in your local development environment
The Functions framework package is a required dependency for functions. For faster builds, we recommend vendoring this package. If you don't, it is downloaded and installed when your function is built.
If you specify an npm engine in the package.json file, the specified version of npm is downloaded at build time. To suppress this behavior, remove it from your package.json file.