Migrate Firebase Extensions to function kits

This guide shows you how to migrate your extensions from the deprecated Firebase Extensions environment to a function kit that you can install and deploy in your own Cloud Functions for Firebase (2nd gen) codebase.

Firebase Extensions managed all aspects of creating, updating, and removing extensions. Function kits package the capabilities of extensions as typical 2nd gen Cloud Functions for Firebase. Because function kits are standard Cloud Functions, you create, update, delete, and troubleshoot them using the Firebase CLI within your Firebase project. This guide prepares you to manage your functions now and adopt updates as they become available.

Throughout this guide, the Stream Cloud Firestore to BigQuery extension (firestore-bigquery-export) is used as an example that shows you the commands and command output for each step of the migration.

Determine your migration path

Firebase encourages all Firebase Extensions publishers to create replacements for their extensions as function kits published on npm. You can check if a function kit replacement is available for your extensions in a few different ways:

  • Go to the Extensions page of the Firebase console for your project. Each extension you have installed indicates if it has a function kit replacement available.

  • Run firebase ext:list inside your Firebase project in a terminal to show which of your installed extensions have official replacements:

    firebase ext:list --project my-project

    i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
✔  extensions: required API firebaseextensions.googleapis.com is enabled
i  extensions: list of extensions installed in my-project:
┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐
│ Extension                          │ Publisher │ Instance ID                    │ State  │ Version │ Your last update    │ Replacement Kit                                   │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/firestore-bigquery-export │ firebase  │ firestore-bigquery-export-zbrp │ ACTIVE │ 0.3.2   │ 2026-06-10 18:35:03 │ @firebase-function-kits/firestore-bigquery-export │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/storage-resize-images     │ firebase  │ storage-resize-images          │ ACTIVE │ 0.3.6   │ 2026-06-03 17:41:24 │                                                   │
└────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘
⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshooting

If an official function kit replacement is available for your extension, you can migrate it using the Migrate to function kits on npm section.

If you can't find a published replacement, you can fork the extension code and create your own replacement because all extensions are open source. To do this, follow the Migrate to a self-created function kit guide.

Select migration path: Migrate to function kits on npm Migrate to a self-created function kit

Migrate to function kits on npm

Check for known migration limitations

Before you start migrating an extension instance, check whether your setup uses any of the following features that require a workaround or aren't yet supported in function kits:

  • Custom Docker repositories and KMS keys require a manual workaround Cloud Functions for Firebase doesn't support replacement system parameters for configuring a custom Docker repository or Customer-Managed Encryption Key (KMS key). If your extension configures either of these parameters, refer to the FAQ workaround.

Before you begin

You need to set up the Firebase CLI and initialize a Firebase project. When using the CLI, make sure you're using firebase-tools version >= 15.32.0, which has the new migration and function kit commands.

Required account permissions and roles

Depending on what needs to be created and configured by the Firebase CLI during migration, the account you're using to authenticate with Firebase and Google Cloud must have the following roles:

  • roles/firebaseextensions.editor
  • roles/cloudbuild.builds.editor
  • roles/artifactregistry.writer
  • roles/run.developer
  • roles/iam.serviceAccountUser
  • roles/iam.serviceAccountCreator
  • roles/cloudfunctions.admin (if you need to do setIamPermissions for public endpoints)
  • roles/secretmanager.admin (if using secrets)
  • roles/serviceusage.serviceUsageAdmin (if you need to enable new APIs)

We recommend using an account that has installed extensions and deployed functions before, since most of these permissions will already have been granted. If your migrating account needs more roles, follow the Google Cloud IAM instructions to add them.

Choose a CLI workflow

To migrate from an extension instance to a function kit available on npm, choose one of the following options:

  • (Recommended) Migrate using the ext:migrate CLI command. This command deploys your function kit replacement before uninstalling the extension it replaces.
  • Migrate using the function kits CLI commands. You can use separate commands to update your extension, install a function kit, configure it like the extension, deploy the kit, and uninstall the extension. This provides more flexibility for reordering commands or performing additional work between steps.

Migrate using ext:migrate

Once per extension instance, start a migration by running:

firebase ext:migrate --project <project-id>

This command walks you through:

  1. Selecting an extension to migrate that has an official function kit replacement available.
  2. Selecting a specific instance of that extension.
  3. Updating the extension to its latest version if necessary.
  4. Installing the function kit, configuring an instance identically to how the extension instance is configured.
  5. Deploying the function kit.
  6. Verifying that the function kit deployed successfully and that all lifecycle hooks, if any, ran.
  7. Uninstalling the extension instance.

If you know the specific extension or extension instance you want to migrate, specify it using the following command-line flags:

firebase ext:migrate --extension firebase/firestore-bigquery-export --project <project-id>

# or

firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --project <project-id>

If you know the specific package you want to migrate to, especially if it's not an official replacement package listed by Google, specify it using the --package flag:

firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --package @firebase-function-kits/firestore-bigquery-export --project <project-id>

Verify a function kit deployment

To verify that the firebase deploy of the kit had no errors, check the deployment logs to see if any lifecycle hooks were triggered. Popular extensions, such as Stream Cloud Firestore to BigQuery, use lifecycle hooks. The following is an example of how a lifecycle hook looks when triggered:

i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i  functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project

These log messages confirm the following:

  • A lifecycle hook was found and executed.
  • A task was queued in the lifecycle hook's associated task queue.
  • A link to Cloud Logging was provided so you can validate that the task completed without errors.

Follow the logs link to the Google Cloud console to validate that there are no errors in the logs and your task queue event was successfully processed. If the lifecycle event didn't execute successfully, you can retrigger it by running:

firebase functions:lifecycle:run <hook-name> <codebase>

If you're deploying a function kit instance for the first time, run:

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

If at any time during validation you decide you want to stop or undo this migration, you can uninstall the kit using the instructions in Uninstall the extension.

Review the function kit README

Some kits might require additional work beyond what is handled automatically by function kits. Review the README for the kit you're installing and follow any additional instructions.

Migrate using the function kits CLI

Before you begin, identify and write down the instance ID of the extension you'd like to migrate to a kit and the npm package name of its replacement kit. You can find both of these using the output of firebase ext:list. See Determining your migration path for an example of using ext:list.

1. Upgrade your extension instance to the latest version

You must update your extension to the latest version to minimize the difference between your extension instance and its replacement kit. If your extension isn't upgraded, there may be significant, breaking changes between your extension instance and its kit replacement. The exported configuration may not match what the kit expects because of parameter changes across versions.

Use one of the following options to update your extension, depending on where it was installed:

  • From the Firebase console
  • From the Firebase CLI using:
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

If you skip this step, the CLI prompts you to upgrade when exporting configuration if your extension isn't on the latest version.

2. Review and install the replacement function kit instance

You can install the function kit using the following CLI command:

firebase functions:kits:install --template migration --no-configure --package <npm-package-name> --project <project-id>

When you pick an instance ID for your kit during installation, make sure to write it down for use later in the migration instructions.

Once the kit is installed, a new directory is created inside your Firebase project with a location like function-kits/<kit-name>/source that contains the npm package with the kit replacing your extension and a basic index.ts file that exports those functions for Firebase to deploy and set custom configuration.

Review the README for the kit and follow any additional instructions listed there.

If you have multiple instances of the kit in the same project, you can repeat this command to create new instances of the same kit. You can also deploy a single kit instance to two different Firebase projects with different configurations (for example, a staging project and a production project). To learn more about these advanced setups, see Advanced migrations.

Worked example:

firebase functions:kits:install --template migration --no-configure --package @firebase-function-kits/firestore-bigquery-export --project my-project

3. Configure the function kit instance identically to the extension

You need to customize this kit instance with a configuration identical to the extension it's replacing. You can export your extension instance configuration into a .env file, which stores parameter, environment variable, and secret reference configuration data for all Cloud Functions, including kits. To export it directly into the configuration file of your kit, run:

firebase ext:export --mode functions --instance <extension-instance-id> --kit-instance <kit-instance-id> --project <project-id>

At the end of this step, the configuration information for this instance is stored in a project-specific .env file in your instance config directory, such as: function-kits/<kit-name>/config-<instance-id>/.env.<project-id>

4. Deploy and verify the kit replacement

Now that the kit is installed and available as a set of functions, you can deploy the kit replacement. Function kits work like standard functions, where each kit instance acts as a separate codebase for organizing your functions. You can choose to deploy all of your functions or just a specific kit instance. While migrating a single extension instance, deploy only that kit instance.

If your kit uses any new parameters that weren't present in the extension instance you migrated from, the Firebase CLI prompts you for them at the beginning of the deployment process. This isn't expected in this worked example from an up-to-date firestore-bigquery-export extension, but many kits prompt for a new parameter for any event trigger source used by the kit. As part of this migration, updated kits use 2nd gen functions where extensions previously used 1st gen functions. In 2nd gen, functions are located near their event sources and added as an additional parameter. In future updates, if new parameters are added, the CLI prompts you on the next deployment.

Worked example:

firebase deploy --only functions:firestore-bigquery-export --project my-project

Output:

=== Deploying to 'my-project'...
i  deploying functions
i  functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
i  functions: ensuring required API bigquery.googleapis.com is enabled...
i  functions: ensuring required API cloudtasks.googleapis.com is enabled...
✔  functions: required APIs are enabled
i  functions: granting declarative IAM roles to managed service account:
   - BigQuery Data Editor
   - BigQuery User
   - Cloud Datastore User
   - Eventarc Event Receiver
   - roles/run.invoker
✔  functions: successfully granted IAM roles
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-fsexportbigquery(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-initBigQuerySync(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-setupBigQuerySync(us-central1)...
✔  functions[kit-firestore-bigquery-export-fsexportbigquery(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-initBigQuerySync(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-setupBigQuerySync(us-central1)] Successful create operation.
i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/us-central1/queues/kit-firestore-bigquery-export-initBigQuerySync.
✔  Deploy complete!

To verify that the firebase deploy of the kit had no errors, check the deployment logs to see if any lifecycle hooks were triggered. Popular extensions, such as Stream Cloud Firestore to BigQuery, use lifecycle hooks. The following is an example of how a lifecycle hook looks when triggered:

i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i  functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project

These log messages confirm the following:

  • A lifecycle hook was found and executed.
  • A task was queued in the lifecycle hook's associated task queue.
  • A link to Cloud Logging was provided so you can validate that the task completed without errors.

Follow the logs link to the Google Cloud console to validate that there are no errors in the logs and your task queue event was successfully processed. If the lifecycle event didn't execute successfully, you can retrigger it by running:

firebase functions:lifecycle:run <hook-name> <codebase>

If you're deploying a function kit instance for the first time, run:

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

If at any time during validation you decide you want to stop or undo this migration, you can uninstall the kit using the instructions in Uninstall the extension.

5. Uninstall the extension

When you've verified your deployed function kit, you can uninstall your extension so that you're not duplicating its behavior once for the kit and once for the extension. You can uninstall all extensions from the Firebase CLI regardless of how you installed them if you pass the --immediate flag:

firebase ext:uninstall <extension-instance-id> --project <project-id> --immediate

Worked example:

firebase ext:uninstall firestore-bigquery-export --project my-project --immediate

Output:

i  extensions: uninstalling firestore-bigquery-export...
i  extensions: deleting extension instance resources in project my-project...
✔  extensions: successfully uninstalled firestore-bigquery-export

Advanced migrations

You can have extensions in multiple Firebase projects that you want to manage with a single codebase. For example, if you deploy the same infrastructure to a testing environment and a production environment, each of which has a documents Cloud Firestore instance that you export to BigQuery, you might have two instances of the firestore-bigquery-export extension installed:

  • export-documents-testing
  • export-documents-production

If you migrated these two extension instances to two function kit instances in a single codebase when working with the Firebase CLI and deployed using firebase deploy --project testing and firebase deploy --project production, each deploy would create two instances in both the testing and production environments.

Instead, replace the two extension instances with one function kit instance of firestore-bigquery-export deployed to multiple projects, where each project has its own configuration. Your configuration directory for the instance should look like the following:

  • config-export-documents/
    • .env.testing
    • .env.production

Each deployment to testing and production creates one instance of your kit with the corresponding configuration. The existing CLI commands create this setup as long as you pass the --project flag in each invocation of ext:migrate or functions:kits:install.

Worked example:

firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project testing --no-configure --template migration

✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? export-documents
✔  Wrote function-kits/firestore-bigquery-export/source/package.json
✔  Wrote function-kits/firestore-bigquery-export/source/tsconfig.json
✔  Wrote function-kits/firestore-bigquery-export/source/.gitignore
✔  Wrote function-kits/firestore-bigquery-export/source/src/index.ts
i  functions: Running npm install
✔  Wrote configuration info to firebase.json
✔  functions: Function kit firestore-bigquery-export successfully installed.

# This creates the export-documents instance with an empty .env.testing file
# for the testing project. Now populate it via export:
firebase ext:export --mode functions --instance export-documents-testing \
  --kit-instance export-documents --project testing

# Repeat the export for production into the same kit instance to create
# .env.production from the export-documents-prod instance:
firebase ext:export --mode functions --instance export-documents-prod \
  --kit-instance export-documents --project production

You now have a single kit instance configured to deploy to your testing and production projects with their respective configurations. If you create an instance in the testing project and run the functions:kits:install command for the same package in the production project, you're prompted with the option to reuse the instance configured for testing or install a second instance.