Set up and use parameters in your extension

Parameters are the mechanism through which a user customizes each installed instance of an extension. Parameters are like the environment variables for an extension. The values for parameters can either be auto-populated (provided by Firebase after installation) or user-configured (specified by the user during installation).

These parameters are available for you to reference in your extension's functions source code, your extension.yaml file, and your POSTINSTALL.md file. Here's the syntax for how to reference a parameter called PARAMETER_NAME:

  • Within your functions source code, use the params module (for example, params.defineInt("PARAMETER_NAME")) or process.env.PARAMETER_NAME.

  • Within extension.yaml and POSTINSTALL.md, use ${param:PARAMETER_NAME}.

    After installation, the Firebase console displays the contents of the POSTINSTALL.md file and populates any parameter references with the actual values for the installed instance.

Auto-populated parameters

Each installed instance of an extension automatically has access to several default auto-populated parameters provided by Firebase (refer to the table below). These parameter values are either the default values for the Firebase project (like the default Storage bucket) or they're extension-specific (like the extension's instance ID).

All auto-populated parameter values are immutable. They are set at the time of project creation or extension installation.

Even though Firebase auto-populates these parameter values for the extension, Firebase doesn't auto-provision the associated products for the user during installation. The user installing the extension must enable the associated and applicable product(s) in their project before installation. For example, if your extension involves Cloud Firestore, the user must set up Cloud Firestore in their project. We recommend notifying your users about these requirements in the PREINSTALL.md file.

Reference for auto-populated parameter Description Parameter value (provided by Firebase)
Parameters with default values from the Firebase project
PROJECT_ID Unique identifier for the Firebase project in which the extension is installed

Generalized format:
project-id

Example value:
project-123

DATABASE_URL The Firebase project's default Realtime Database instance URL

Generalized format:
https://project-id-default-rtdb.firebaseio.com
(US instances)
or
https://project-id-default-rtdb.region-code.firebasedatabase.app
(non-US instances)

Example value:
https://project-123-default-rtdb.firebaseio.com

DATABASE_INSTANCE

The Firebase project's default Realtime Database instance name

Usually, this value is the same as the project ID, or ends in -default-rtdb.

Generalized format:
project-id

Example value:
project-123

STORAGE_BUCKET The Firebase project's default Cloud Storage bucket name

Generalized format:
project-id.appspot.com

Example value:
project-123.appspot.com

Parameter with default value from the extension installation
EXT_INSTANCE_ID

Unique identifier for the installed extension instance

This value is generated from the name field specified in the extension.yaml file.

Generalized format for 1st installed instance (automatically assigned by Firebase; cannot be user-modified during installation):
name-from-extension.yaml

Example value:
my-awesome-extension


Generalized format for 2nd-installed instance and above (automatically assigned by Firebase; can be user-modified during installation):
name-from-extension.yaml-4-digit-alphanumeric-hash

Example value:
my-awesome-extension-6m31

User-configured parameters

To enable a user to customize each installed instance of an extension, you can ask the user to specify parameter values during installation. To request these values, you set up the prompts in the params section of your extension.yaml file.

Here's an example params section, followed by a table describing all available parameter fields.

# extension.yaml
...

# Parameters (environment variables) for which the user specifies values during installation
params:
  - param: DB_PATH
    label: Realtime Database path
    description: >-
      What is the Realtime Database path where you will write new text
      for sentiment analysis?
    type: string
    validationRegex: ^\S+$
    validationErrorMessage: Realtime Database path cannot contain spaces.
    example: path/to/posts
    required: true

  - param: TEXT_KEY
    label: Key for text
    description: What is the name of the key that will contain text to be analyzed?
    type: string
    default: textToAnalyze
    required: true

In the params section of your extension.yaml file, use the following fields to define a user-configured parameter:

Field Type Description
param
(required) 		string Name of the parameter
label
(required) 		string

Short description for the parameter

Displayed to the user when they're prompted for the parameter's value

description
(optional) 		string

Detailed description for the parameter

Displayed to the user when they're prompted for the parameter's value

Supports markdown

type
(optional) 		string

Input mechanism for how the user sets the parameter's value (for example, enter text directly or select from dropdown list)

Valid values include the following:

  • string: allows free-form text entry (as limited by your validationRegex)
  • select: allows selection of one entry from a pre-defined list of options. If you specify this value, you must also define the options field.
  • multiSelect: allows selection of one or more entries from a pre-defined list of options. If you specify this value, you must also define the options field.
  • selectResource: allows selection of a specific type of Firebase resource (such as a Cloud Storage bucket) from the user's project.

    When you specify a parameter of this type, users will get a more user-friendly selection widget in the installation UI; for this reason, use selectResource parameters whenever possible.

    If you specify this value, you must also define the resourceType field.

  • secret: allows storage of sensitive strings, such as API keys for third-party services. These values will be stored in Cloud Secret Manager.

    Cloud Secret Manager is a paid service, the use of which might result in charges for users who install your extension. If you use the secret parameter type, be sure to document in your PREINSTALL file that your extension uses Cloud Secret Manager.

If this field is omitted, the parameter defaults to type of string.

options
(required if parameter type is select or multiSelect) 		list

List of values from which the user can select

Include label and value fields within the options field:

  • label (string): short description of the selectable option
  • value (string): actual value of the selectable option

The value field is required for the options field.
If label is omitted, the list option defaults to display value.
resourceType
(required if parameter type is selectResource) 		string

The type of Firebase resource to prompt the user to select. Currently, only Cloud Storage buckets support resource selectors:

Resource type Type ID
Cloud Storage bucket storage.googleapis.com/Bucket

Unknown resourceType values will be ignored and the UI will render the parameter as a free-form string input field.
example
(optional) 		string

Example value for the parameter
validationRegex
(optional)
(only applicable when the parameter type is string) 		string

Regex string for validation of the parameter's user-configured value

Regex is compiled using the go library: RE2

For details about validation, refer to Validation and error messaging below.

validationErrorMessage
(optional) 		string

Error message to display if the validationRegex fails

For details about error messaging, refer to Validation and error messaging below.

default
(optional) 		string

Default value for the parameter if the user leaves the parameter's value blank

If applicable, you can specify an auto-populated parameter value for the default value (for an example, refer to the IMG_BUCKET parameter of the Resize Images extension).

required
(optional) 		boolean

Defines whether the user can submit an empty string when they're prompted for the parameter's value

If required is omitted, this value defaults to true (that is, a required parameter).

immutable
(optional) 		boolean

Defines whether the user can change the parameter's value after installation (for example, if they reconfigure the extension)

If immutable is omitted, this value defaults to false.

Note: If you define a "location" parameter for the deployed functions of your extension, then you should include this immutable field in its param object.

Validation and error messaging for user-configured values

When you set up a parameter with the type of string, you need to define appropriate regex validation via the parameter's validationRegex field.

Also, for many extensions, a commonly requested parameter value is a database path or Cloud Storage bucket. Be aware that during install, reconfigure, or update, the Extensions service does not validate the following at the time of parameter value entry:

  • Whether the specified database or Cloud Storage bucket is set up within the user's Firebase project
  • Whether the specified database path exists within the user's database

However, when the extension is actually deploying its resources, the Firebase console or the Firebase CLI will display an error message if the referenced database or Cloud Storage bucket is not yet set up in the project.

We strongly recommend that you notify users in the PREINSTALL file about these requirements so that when they install your extension, it successfully installs and works as expected.

System parameters

System parameters control the basic configuration of an extension's resources. Since they are meant to control resource configuration, they are not accessible as environment variables from within your function code.

You don't normally need to declare anything for these parameters in extension.yaml. They are automatically defined for every extension instance, and users have the opportunity to set custom values when they install your extension.

However, if your extension has special resource requirements, you can set specific values on a per-resource level in extension.yaml. These per-resource configuration settings will override the user's extension instance-wide settings. For example:

resources:
- name: high_memory_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function needs at least 1GB of memory!
  properties:
    httpsTrigger: {}
    runtime: nodejs18
    availableMemoryMb: 1024
- name: normal_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function has no special memory requirements. It will use the
    default value, or the value of `firebaseextension.v1beta.function/memory`
  properties:
    httpsTrigger: {}
    runtime: nodejs18

The available system params are:

Name Label (human friendly) Corresponding field in properties Description
firebaseextensions.v1beta.function/location Location location What region should Cloud Functions be deployed to?
firebaseextensions.v1beta.function/memory Function memory memory How many megabytes of memory should be allocated to each function?
firebaseextensions.v1beta.function/timeoutSeconds Function timeout timeout How many seconds should functions run before timing out?
firebaseextensions.v1beta.function/vpcConnectorEgressSettings VPC Connector Egress vpcConnectorEgressSettings Controls outgoing traffic when a VPC connector is configured
firebaseextensions.v1beta.function/vpcConnector VPC Connector vpcConnector Connects Cloud Functions to specified VPC connector.
firebaseextensions.v1beta.function/minInstances Minimum function instances minInstances The minimum number of instances of this function to run at once
firebaseextensions.v1beta.function/maxInstances Maximum function instances maxInstances The maximum number of instances of this function to run at once
firebaseextensions.v1beta.function/ingressSettings Ingress Settings ingressSettings Controls where incoming traffic is accepted from
firebaseextensions.v1beta.function/labels Labels labels Labels to apply to all resources in the extension