Overview for building an extension

A Firebase Extension performs a specific task or set of tasks in response to HTTP requests or to triggering events from other Firebase products, like Cloud Firestore or Firebase Cloud Messaging.

Firebase maintains a collection of official Firebase extensions, but you can also build your own extension. For example, your extension can perform a specific task that your app regularly needs, or your extension can enable easier access to your company's API. After you build your extension, you can share it with others. Those users can install and configure the extension in their own projects using the Firebase CLI.

You can think of an extension as having three main components:

  • Cloud Functions source code (for example, in an index.js file)
  • A specification file (extension.yaml) that defines your extension's metadata, such as its triggers and IAM access roles as well as any user-configured parameters (environment variables) for your extension
  • Documentation to help your users configure and use your extension

Learn more about the structure of an extension in the following section, or get started building an extension right away.

Learn more about an extension's structure (below) Get started building an extensionarrow_forward

What's the structure of an extension?

To build your extension, you'll create content for the extension's source directory. This section describes the standard structure for an "extension directory" (directories are in bold). This extension is called my-awesome-extension.

my-awesome-extension/
    functions/
        index.js
        package.json
    extension.yaml
    PREINSTALL.md
    POSTINSTALL.md
  • functions — Contains the files for the source code for the extension

    • index.js — Contains the main source code for your functions
    • package.json — Lists the npm packages for your functions source code and specifies the entry point for your functions source code (like index.js)
  • extension.yaml — Contains your extension's metadata and defines the resources created, the Google APIs and IAM access roles required for operation, and any user-configured parameters (environment variables) for your extension

  • PREINSTALL.md — Describes how the extension works, any necessary pre-installation tasks, configuration requirements, and important details about the extension

  • POSTINSTALL.md — Describes any post-installation integration requirements and the specific usage instructions for the extension

Before building your extension, we recommend installing at least one of the official Firebase extensions using the CLI to better understand how your users experience installing an extension. Try to compare each stage of the process with the content of the extension directory (especially from the extension.yaml, PREINSTALL.md, and POSTINSTALL.md files).

Resources for an extension

Every Firebase project contains several types of "resources". Project resources can include things like database instances, Cloud Storage buckets, and deployed Cloud Functions.

When a user installs an extension, Firebase creates new extension-specific resources in their Firebase project (specifically, Cloud Functions). When you build your extension, you define these resources in the extension's specification file, extension.yaml (specifically, as the resource type firebaseextensions.v1beta.function).

Note that, if the user uninstalls an extension, all the resources that Firebase created specifically for that instance of the extension to operate (like a set of functions) are deleted. However, the following are not deleted:

  • Any artifacts created by the extension (like stored images).

  • Any other resources in the Firebase project, like a database instance or Storage bucket. Even if the extension interacted with these other resources, they are not extension-specific, so they aren't deleted if the extension is uninstalled.

Next Steps

  • Install at least one of the official Firebase extensions using the CLI to better understand how your users experience installing an extension.

  • Review the getting started guide to understand the basic concepts and workflow for building your own extension.

  • Try modifying one of the official Firebase extensions before stepping up to building your own completely new extension. Start by running git clone on the extension repository, then modify and test one of the extensions.