Install a Firebase Extension

You can install (and manage) any of the official Firebase extensions using either the Firebase console, the Firebase CLI (command-line interface), or using an autogenerated SDK.

Make sure to review the differences in the supported actions for each installation method.


Installation using an autogenerated SDK is a new option for installing and managing extensions. With this option, you use the CLI to automatically generate a Node SDK for a specific extension version, which you can import as an ordinary dependency in your JavaScript or TypeScript Cloud Functions.

This auto-generated SDK contains:

  • An interface representing the extension's parameters, and type declarations for most non-primitive parameter types.
  • A constructor function that initializes an instance of the extension
  • An extension class that contains Eventarc triggers for all of the events emitted by the extension.

Once you've generated an extension SDK, all configuration of the extension happens in code.

Using this installation option can greatly simplify the management of multiple extension instances, particularly in projects that contain Cloud functions defined outside of extensions.


To install or manage extensions, you must be assigned one of these roles: Owner or Editor or Firebase Admin.

To install an extension, your project must be on the Blaze (pay as you go) plan. Although there is no charge for installing an extension, you might be charged for your use of Firebase services or Cloud services such as Cloud Secret Manager, if your usage exceeds the services' free tier.

Before you begin

  1. If you haven't already, add Firebase to your project.

  2. If you haven't already, upgrade your project to the Blaze (pay as you go) plan.

  3. Install or update to the latest version of the Firebase CLI.

  4. Take note of either your Firebase project ID or previously configured project alias.

    • Project ID — Run firebase projects:list from anywhere on your computer.
    • Project alias — Run firebase use from your local app directory.

Step 1: View detailed information about an extension

This step is optional, but strongly recommended.

Before installing a Firebase Extension, we recommend that you review detailed information about the extension, including:

  • How the extension works, any pre-installation tasks, and details about the extension
  • General identifying information and description
  • Whether the extension's tasks require a billing account
  • Google services (APIs) and access roles required for operation
  • Resources created for the extension (like functions)
  • Descriptions of user-configurable parameters

To view an extension's detailed information:

  1. Make sure that you've set up your environment and selected an extension.

  2. Run the extension-info command from anywhere on your computer:

    firebase ext:info publisher-id/extension-id

    The publisher-id and extension-id arguments are required and can be found on the extension's preinstall details page.

Step 2: Install an extension

Before installation, review the basic specifications for the extension (such as APIs enabled, resources created, access granted, etc.) and its billing requirements.

Before you continue, make sure that you've set up your environment and selected an extension.

Initialize Cloud Functions for Firebase

If you're starting a new project or if your project does not already use Cloud Functions for Firebase, run init functions:

cd your-project
firebase init functions

Choose TypeScript or JavaScript as your functions language.

If your project already has Cloud Functions initialized, make sure you are using version 5.1.0 or newer of the firebase-functions package:

cd your-project/functions
npm upgrade --save firebase-functions

If you use ESLint, you might also want to exclude generated SDKs from your configuration (.eslintrc.js):

ignorePatterns: [
  "/generated/**/*", // Ignore generated files.
  // ...
],

Generate an extension SDK

From your local Firebase directory, run the ext:sdk:install command.

firebase ext:sdk:install publisher-id/extension-id@version

For example, to install version 0.1.34 of the firestore-send-email extension:

firebase ext:sdk:install firebase/firestore-send-email@0.1.34

The publisher-id and extension-id are required and can be found on the extension's preinstall details page on extensions.dev. The @version part is optional; if you omit it, the tool installs the latest version.

There are two options you can specify:

  • --force: Do all of the following without further confirmation:

    • Autogenerate the SDK even if one has already been generated for the same extension and version.
    • Install the autogenerated SDK package in the Cloud Functions Node project.

  • --codebase: The name of the codebase to add the SDK to. If unspecified, the command adds the SDK to the default codebase, functions.

This command creates a Node package containing an SDK automatically generated for the extension, and adds it to one of your project's Cloud Functions codebases. In the default codebase (functions), the SDK is saved to the following location: 

functions/generated/extensions/publisher-id/extension-id/version

After generating the SDK, the command will ask if you want to also install the SDK into your Cloud Functions Node project. Answer Yes to this prompt.

Configure extension instances

To configure the extension, import the SDK, and for each extension instance you want to install, call the constructor function, passing to it a project-unique instance ID and the configuration parameters required by the extension.

  1. In your Cloud Functions source, import the constructor using the statement printed by the ext:sdk:install command.

    TypeScript

    For example, if you generated an SDK for the firestore-send-email extension, the import statement would look something like the following:

    import { firestoreSendEmail } from "@firebase-extensions/firebase-firestore-send-email-sdk";

    If the extension requires any secret values such as passwords, you also need the defineSecret function from the Cloud Functions SDK:

    import { defineSecret } from "firebase-functions/params";

    JavaScript

    For example, if you generated an SDK for the firestore-send-email extension, the require statement would look something like the following:

    const { firestoreSendEmail } = require("@firebase-extensions/firebase-firestore-send-email-sdk");

    If the extension requires any secret values such as passwords, you also need the defineSecret function from the Cloud Functions SDK:

    const { defineSecret } = require('firebase-functions/params');

  2. For each instance you want to configure, call the constructor function and export the result.

    Give each instance a unique ID, containing only lower case letters, numbers, and hyphens.

    TypeScript

    export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    JavaScript

    exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    Note that secret values must be specified using the defineSecret function.

  3. Then, to deploy the extensions you configured, run: 

    firebase deploy --only functions --project=projectId-or-alias

    All the usual Cloud Functions deployment options apply. For example, to deploy a single extension instance from a specific codebase: 

    firebase deploy --only functions:codebase:extension-instance-id --project=projectId-or-alias

Step 3: Complete post-install setup

Some extensions have required or optional steps for you to complete before using them. Find these instructions in your extension's post-install details page in the Extensions dashboard of the Firebase console (the specific link to the dashboard is displayed in the terminal after installation).

You can also find these instructions in the POSTINSTALL.md file included in the extension's source directory.

Create Firebase resources

If you configured the extension to use Firebase resources (Cloud Firestore collections, Realtime Database paths, Cloud Storage buckets) that don't already exist, create them before using the extension.

Create Eventarc event handlers

Some extensions publish to Eventarc when important events happen during execution. If an extension publishes events, you can write functions that react to these events with your own custom logic. This can be useful, for example, to notify users when long-running tasks complete, or to post-process the output of an extension function.

If you want to define handlers for any of the events emitted by the extension, you can do so using each instance's trigger methods:

TypeScript

export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

JavaScript

exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

You must export the event handler along with the extension instance.

After defining an event handler, and after every time you make changes to one, redeploy both the extension and the handler.

Install multiple extension instances

You can install the same extension more than once in the same project. Each installed instance can have its own customized configuration and its own extension resources. You identify and refer to each installed instance using its instance ID, which is unique within your project.

Call the autogenerated SDK's constructor function once for every instance you want to install and configure.

Next Steps

  • View the details and the configuration of your installed extension in the Firebase console.

  • Monitor the activity of your installed extension, including checks on its health, usage, and logs.

  • Using the Firebase console, manage your installed extension. For official Firebase extensions, you can reconfigure or uninstall your extension, as well as update your extension to the latest version.

  • As a best practice for all projects, make sure to set up budget alerts for your project and monitor your Usage and billing dashboard in the Firebase console.