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 .

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:

 options: - label: value: - label: value: - label: value:

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: