Create user documentation for your extension

Every extension must have documentation that teaches users what the extension does and how to use it.

The minimum, required, documentation is this set of three markdown files:

  • PREINSTALL.md
  • POSTINSTALL.md
  • CHANGELOG.md

In addition, you should also consider producing:

  • A README file for the extension's public repository.
  • Longer-form tutorials, guides, and reference published on your own website and linked in your PREINSTALL.md.

To learn some best practices and common phrasing and structure, we recommend reviewing the files available with the official Firebase extensions.

Creating a README

Your extension directory can optionally contain a README. Note that the firebase ext:dev:init command doesn't automatically generate one for you.

The Firebase CLI, though, does support the following convenience command to auto-generate a README file containing content pulled from your extension.yaml file and your PREINSTALL.md file:

firebase ext:info ./path/to/extension --markdown > README.md

All the README files for the official Firebase extensions are generated using this command.

Add installation information

After you write or generate a README, add installation information to it. You can use the following snippet as a template:

---

## 🧩 Install this extension

### Console

[![Install this extension in your Firebase project](https://www.gstatic.com/mobilesdk/210513_mobilesdk/install-extension.png "Install this extension in your Firebase project")][install-link]

[install-link]: https://console.firebase.google.com/project/_/extensions/install?ref=publisher_id/extension_name

### Firebase CLI

```bash
firebase ext:install publisher_id/extension_name --project=[your-project-id]
```

> Learn more about installing extensions in the Firebase Extensions documentation:
> [console](https://firebase.google.com/docs/extensions/install-extensions?platform=console),
> [CLI](https://firebase.google.com/docs/extensions/install-extensions?platform=cli)

---

Writing a PREINSTALL file

The PREINSTALL file is your extension's overview, a type of "marketing" page.

What content is in this file?

  • Comprehensive description of your extension's functionality
  • List of prerequisites, such as database setup or access to a non-Google service (example)
  • Brief description of any pre-installation tasks and their instructions
  • Brief description of any post-installation tasks (example) (detailed instructions go in POSTINSTALL)
  • Brief description of any billing implications (start with boilerplate text)

Where does this content display to the user?

Image of pre-install content in Firebase console
Pre-install content in the Firebase console

Large image of pre-install content in Firebase console

  • On the extension's page on extensions.dev.
  • Your source code repo for your extension (inside the extension directory)
  • As part of the extension's README (if you use the Firebase CLI --markdown > README.md flag)

PREINSTALL files cannot access the parameter values for the extension, so you should not expect parameter references to render with actual values.

What are some best practices?

  • Keep the full content of the PREINSTALL file to under one page, if possible
  • Provide the level of detail that an end user absolutely needs to know before installing the extension
  • Put detailed instructions in the POSTINSTALL file or other supplementary files
  • Briefly mention if you provide other tools or scripts to support the extension

Writing a POSTINSTALL file

The POSTINSTALL file is your extension's detailed post-installation instructional page.

What content is in this file?

  • Detailed instructions for any required post-installation tasks, like setting up Firebase security rules or adding client-side code (example)
  • Generic instructions for how to immediately try out the installed extension (for example, "go to the console, then do this")
  • Basic information about how to trigger the extension, especially for HTTP request-triggered extensions
  • Brief directions for how to monitor the installed extension (start with boilerplate text)

Where does this content display to the user?

Image of post-install content in Firebase console
Post-install content in the Firebase console

Large image of post-install content in Firebase console

  • In the Firebase console after a user installs your extension (in the installed extension's detail card)

  • Your source code repo for your extension (inside the extension directory)

POSTINSTALL files can access the parameter values and several function-related variables for the extension. When the POSTINSTALL content is displayed in the Firebase console, the actual values display rather than the parameter or variable references. Learn more below about how to reference parameters and variables in your POSTINSTALL file.

What are some best practices?

  • Keep the full content of the POSTINSTALL file concise, but descriptive.
  • Section the content using headings to break apart distinct tasks or concepts.
  • Consider publishing detailed instructions for a specific workflow or task on your website (example) or in supplementary markdown files within the extension repository (example).
  • Reference parameters and function-related variables so that the user sees their configured values in context of the instructions

Referencing parameters and variables

After installation, the Firebase console displays the contents of the extension's POSTINSTALL file. If you reference parameters and function-related variables (see table below) in your POSTINSTALL file, then the console populates these references with the actual values for the installed instance.

Access configured parameter values in the POSTINSTALL file using the following syntax: ${param:PARAMETER_NAME}

You can also reference the following function-related variables in your POSTINSTALL file only. Firebase supports these variables so that you can more easily provide guidance to your users post-installation. They're only available to use in the POSTINSTALL file because values for these variables aren't available until after installation.

In this table, function-name is the value of the name field in the function's resource object within extension.yaml.

Reference for function-related variable Description Variable value (auto-populated by Firebase after extension installation)
${function:function-name.location}
Location where the function is deployed Example value:
us-central1
${function:function-name.name}
Name of the final deployed function, which includes the extension's instance ID

Generalized format:
ext-extension-instance-id-function-name

Example value:
ext-my-awesome-extension-6m31-yourFunctionName

${function:function-name.url} (only applicable for HTTP functions)
URL of the final deployed function, to which client code can make HTTP requests

Generalized format:
https://deployment-location-project-id.cloudfunctions.net/name-of-final-deployed-function

Example value:
https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

Documenting how to trigger an extension

In your extension's user documentation, you need to instruct your users about how to trigger your extension. These instructions can be as detailed as you think is necessary, but keep in mind the best practices for writing a POSTINSTALL file. For guidance on how to provide these instructions, expand the section below that applies to your extension.

Writing a CHANGELOG file

What content is in this file?

Every extension must have a CHANGELOG.md file that documents the changes included in each new version of your extension you publish. Put each version under a level 2 header (##); otherwise, you can use whatever Markdown formatting you like.

The following example is an excerpt from one of the official extensions:

## Version 0.1.3

feature - Support deletion of directories (issue #148).

## Version 0.1.2

feature - Add a new param for recursively deleting subcollections in Cloud
Firestore (issue #14).

fixed - Fixed "cold start" errors experienced when the extension runs after a
period of inactivity (issue #48).

## Version 0.1.1

Initial release of the _Delete User Data_ extension.

Where does this content display to the user?

  • In the Firebase console and CLI, when users upgrade to new versions of your extension. The Firebase console and CLI display only the changes that would take effect if the user were to complete the upgrade.
  • Your extension's source code repo (inside the extension directory).