> Documentation index: https://firebase.google.com/docs/extensions/llms.txt |---|---| | **Select migration path:** | [Migrate to function kits on npm](https://firebase.google.com/docs/extensions/users/migrate.md.txt) [Migrate to self-created function kit](https://firebase.google.com/docs/extensions/users/migrate-self-created.md.txt) | If a publisher hasn't created an official replacement kit distributed on npm, this guide walks you through the steps to fork their extension and set it up as a local function kit. ## 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](https://firebase.google.com/docs/extensions/faq-and-troubleshooting.md.txt#docker-or-kms-workaround). ## Before you begin You need to [set up the Firebase CLI](https://firebase.google.com/docs/cli.md.txt#setup_update_cli) and [initialize a Firebase project](https://firebase.google.com/docs/cli#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. > [!NOTE] > **Note:** All CLI commands throughout this guide include the `--project > ` flag to explicitly specify your target project. If you are working in your default project configured in `.firebaserc`, you can omit the `--project` flag. ### 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](https://cloud.google.com/iam/docs/grant-role-console) to add them. ### 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](https://console.firebase.google.com/project/_/extensions) - From the Firebase CLI using: - `firebase ext:update --project firebase deploy --only extensions --project ` If you skip this step, the CLI prompts you to upgrade when exporting configuration if your extension isn't on the latest version. ## Fork the extension into a local function kit Before you start converting an extension to a local function kit, make sure that the extension source code is inside your Firebase project. To do this, clone the extension repository from GitHub, create a directory inside your Firebase project root, and copy the extension's `functions/` folder and `extension.yaml` into it: ```bash mkdir -p path/to/kit cp -r /path/to/extension-source/functions/* path/to/kit/ cp /path/to/extension-source/extension.yaml path/to/kit/. ``` Follow Steps 1 through 8 from the [publisher migration guide](https://firebase.google.com/docs/extensions/publishers/migrate.md.txt#inventory-the-extension) to migrate your extension source code to a 2nd gen function. Then continue with the following steps. ### Make your local kit support exported function region and advanced parameters In a local function kit, the Firebase CLI doesn't generate an `index.ts` file to set up the package and configure it to use migrated system parameters. To use function region and advanced parameters that were configured for your extension, set up your `index.ts` file to read the format exported by `firebase ext:export --mode functions` into an environment variable file. Specifically, in the top-level `index.ts` file that exports your functions, define a parameter for `FUNCTION_DEFAULT_REGION` and call [`setGlobalOptions`](https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.globaloptions.md.txt) with environment variables of the form `EXT_MIGRATED_SYSTEM_`, similar to the [`index-kit-migration.ts`](https://github.com/firebase/firebase-tools/blob/main/templates/init/functions/typescript/index-kit-migration.ts) template used by the CLI: ```typescript import { setGlobalOptions } from "firebase-functions"; import { MemoryOption, VpcEgressSetting, IngressSetting } from "firebase-functions/v2/options"; import { defineString } from "firebase-functions/params"; export const regionParam = defineString("FUNCTION_DEFAULT_REGION", { input: { text: { nonEmpty: true } }, description: "Global default region where functions should be deployed. Can be overridden per-function.", }); setGlobalOptions({ region: regionParam, memory: (process.env.EXT_MIGRATED_SYSTEM_MEMORY as MemoryOption) ?? undefined, timeoutSeconds: process.env.EXT_MIGRATED_SYSTEM_TIMEOUTSECONDS ? Number(process.env.EXT_MIGRATED_SYSTEM_TIMEOUTSECONDS) : undefined, vpcConnectorEgressSettings: process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS && process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS !== "VPC_CONNECTOR_EGRESS_SETTINGS_UNSPECIFIED" ? (process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS as VpcEgressSetting) : undefined, vpcConnector: process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOR ?? undefined, maxInstances: process.env.EXT_MIGRATED_SYSTEM_MAXINSTANCES ? Number(process.env.EXT_MIGRATED_SYSTEM_MAXINSTANCES) : undefined, minInstances: process.env.EXT_MIGRATED_SYSTEM_MININSTANCES ? Number(process.env.EXT_MIGRATED_SYSTEM_MININSTANCES) : undefined, ingressSettings: (process.env.EXT_MIGRATED_SYSTEM_INGRESSSETTINGS as IngressSetting) ?? undefined, // Parses a comma-separated string of key:value pairs into a key-value object // (for example, "key1:value1,key2:value2" -> { key1: "value1", key2: "value2" }). labels: process.env.EXT_MIGRATED_SYSTEM_LABELS ? process.env.EXT_MIGRATED_SYSTEM_LABELS.split(",").reduce | undefined>( (acc, curr) => { const [key, value] = curr.split(":"); const trimmedKey = key?.trim(); const trimmedValue = value?.trim(); if (!trimmedKey || !trimmedValue) { return acc; } acc = acc ?? {}; acc[trimmedKey] = trimmedValue; return acc; }, undefined, ) : undefined, }); // Re-export all functions so the Firebase CLI can deploy them export * from "./your-functions"; ``` ### Test your kit prior to migration You now have a local function kit that, when deployed, behaves identically to a new installation of your extension. The next step is to verify and fix any issues accidentally introduced along the way before migrating your production extension instances to it. First, add your fork as a local kit, configure it, and deploy it to a test project. Local function kits must live inside your Firebase project, so if the cloned extension repository is outside your Firebase project, move it inside the project directory. Then run the following kit installation command to install it as a local kit: ```bash firebase functions:kits:install --directory --project ``` This command guides you through picking a kit ID, an instance ID, and a configuration for your first test instance. It then modifies your `firebase.json` file to register a local kit pointing to your forked directory, with configurations for each instance stored in a `.env` file at `function-kits//config-`. Deploy your local kit into a test project with the appropriate resources to test its behavior. If you already have a test project set up from testing your extension, run the following command: ```bash firebase deploy --only functions: --project ``` **Worked example:** Stream Cloud Firestore to BigQuery (`firestore-bigquery-export`) Verify the Cloud Firestore to BigQuery sync end-to-end: 1. In the Cloud Firestore page of the Firebase console, create the collection you set as `COLLECTION_PATH` (`users`) if it doesn't already exist. 2. Create a document named `bigquery-mirror-test` containing any fields with any values. 3. In the BigQuery page of the Google Cloud console, query the raw changelog table. It should contain a single row logging the document creation: ```sql SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog` ``` 4. Query the **latest view** , which should return the latest change event for the only document present (`bigquery-mirror-test`): ```sql SELECT * FROM `PROJECT_ID.analytics.users_raw_latest` ``` 5. Delete the `bigquery-mirror-test` document in Cloud Firestore. It disappears from the latest view, and a `DELETE` event is appended to the raw changelog table. You can inspect the full history of a single document with: ```sql SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog` WHERE document_name = "bigquery-mirror-test" ORDER BY timestamp ASC ``` **Differences from testing the extension:** - The trigger deploys as `kit--fsexportbigquery`, not `ext--fsexportbigquery`. Look for that name in the Cloud Functions dashboard and logs. - Your code runs in the Firebase Local Emulator Suite as standard functions. You can set parameter values to use in the emulator with `.env.local`. You can also unit test your code using the `firebase-functions-test` SDK as described in [Unit testing of Cloud Functions](https://firebase.google.com/docs/functions/unit-testing.md.txt). - Provisioning is no longer driven by the Extensions runtime. If the changelog table is missing after deploy, rerun the setup task manually: `firebase functions:lifecycle:run afterFirstDeploy `. The task is idempotent, so rerunning it reconciles the dataset, table, and views. - Param values come from `.env` rather than the installation form, so reruns of `firebase deploy` are non-interactive once `.env` is complete. ### (Optional) Clean up from testing If you want to remove this test instance after testing, uninstall it: ```bash firebase functions:kits:uninstall --instance --project ``` This deletes all cloud resources created by deploying the kit and removes its instance configuration. If you only have one instance of the kit, this also removes the kit entry from `firebase.json`. It does not delete your local source code directory. When you install the kit for your production migration, you can pick a kit ID again. ## Migrate from extensions to your local kit Now that your local kit is tested, you can migrate your live deployed extension instance. ### 1. Install the replacement function kit instance Install your local function kit, passing `--no-configure` to skip manual configuration so that the next step can export your existing extension configuration directly into this kit instance: ```bash firebase functions:kits:install --no-configure --directory --project ``` ### 2. 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: ```bash firebase ext:export --mode functions --instance --kit-instance --project ``` 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//config-/.env.` > [!NOTE] > **Note:** If you haven't upgraded your extension to the latest version before exporting, the export command prompts you to do so. ### 3. 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](https://firebase.google.com/docs/functions/organize-functions.md.txt#organize_functions_in_codebases) 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:** ```bash 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! > [!NOTE] > **Note:** It can take a few minutes for Eventarc to fully provision and start accepting events. We recommend waiting a few minutes before verifying your kit if it's event triggered. If you delete your extension immediately without verification, you might have a brief period of downtime while provisioning finishes. 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: ```bash firebase functions:lifecycle:run ``` If you're deploying a function kit instance for the first time, run: ```bash firebase functions:lifecycle:run afterFirstDeploy ``` 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](https://firebase.google.com/docs/extensions/migration-best-practices.md.txt#undoing-migration). Once you've verified that the initial deployment of your function kit has completed successfully, you need to validate that the functionality of the kit is actually working as expected. Because the extension itself is still running, you need to be careful that what you're checking is not just that one of the two has worked, since the extension has been and will continue to work. In the case where the processing isn't changed and you don't see duplicate results from the extension and kit, the best option is to directly examine the logs for the kit after triggering the kit's functionality. **Worked Example:** Stream Cloud Firestore to BigQuery With the Stream Cloud Firestore to BigQuery Extension writes to both the Raw Changelog Table (`*_raw_changelog`) and latest view table (`*_raw_latest`) will deduplicate if the same event is delivered to the kit and the extension. So you can't use the presence of any rows or duplicate rows in BigQuery to validate the kit is working. You can view functions logs shortly after writing to your Firestore collection using `firebase functions:logs` and look for a log entry that indicates it successfully processed a write. For this kit with the default instance ID of `firestore-bigquery-export` would look like: ```bash 2026-09-25T19:52:46.328612Z I kit-firestore-bigquery-export-fsexportbigquery: Started execution of extension 2026-09-25T19:52:46.328644Z I kit-firestore-bigquery-export-fsexportbigquery: {"message":"Firestore event received by onDocumentWritten trigger","document_name":"projects/extensions-eventarc-testing/databases/(default)/documents/exported-messages/cmGP6XLyksqGdw2OgTOq","operation":0,"event_id":"9f59a2a4-1a5e-4c41-a32d-561e3c734502"} 2026-09-25T19:52:46.616064Z I kit-firestore-bigquery-export-fsexportbigquery: Completed execution of extension 2026-09-2 ``` > [!NOTE] > **Note:** The specific Firestore event received log `document_name` will vary based on your configuration. If you have a lot of logs, you can filter down to a specific kit function using the following command: ```bash firebase functions:log --only ``` To find the specific function names for a kit instance, you can use the following command: ```bash firebase functions:list | grep kit- ``` For this example: ```bash firebase functions:list | grep kit-firestore-bigquery-export │ kit-firestore-bigquery-export-fsexportbigquery │ v2 │ google.cloud.firestore.document.v1.written │ │ kit-firestore-bigquery-export-initBigQuerySync │ v2 │ taskQueue │ │ kit-firestore-bigquery-export-setupBigQuerySync │ v2 │ taskQueue │ │ kit-firestore-bigquery-export-syncBigQuery │ v2 │ taskQueue │ ``` ### 4. 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: ```bash firebase ext:uninstall --project --immediate ``` **Worked example:** ```bash 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:** ```bash 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. ```bash # 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 ``` > [!NOTE] > **Note:** Some console output has been omitted for brevity. 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.