After you migrate from Firebase Extensions to a function kit, you manage your kit instances as standard 2nd gen Cloud Functions in your Firebase project. This guide covers how to install new function kits directly from npm without migrating an existing extension, update kit parameters and global options, upgrade npm package versions as publishers release updates, and roll back a migration if needed.
Using a function kit from an npm package without migrating
If you're not migrating from an extension, using a function kit consists of two parts:
Installing the kit
You can install a function kit using the following CLI command:
firebase functions:kits:install --package <npm-package-name>
Worked example:
firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project my-project
✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? firestore-bigquery-export
i function-kits/firestore-bigquery-export/source/package.json is unchanged
i function-kits/firestore-bigquery-export/source/tsconfig.json is unchanged
i function-kits/firestore-bigquery-export/source/.gitignore is unchanged
i functions: Running npm install @firebase-function-kits/firestore-bigquery-export@next --save-prefix=^...
i functions: Building TypeScript source...
✔ Wrote configuration info to firebase.json
i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
Prompting for parameters for codebase firestore-bigquery-export:
✔ Enter a string value for FUNCTION_DEFAULT_REGION:
(Global default region where functions should be deployed. Can be overridden per-function.) us-east1
✔ Enter a string value for BigQuery Project ID:
(Override the default project for BigQuery instance. This can allow updates to be directed to a BigQuery
instance on another GCP project.) my-bigquery-project
✔ Enter a string value for Firestore Instance ID:
(The Firestore database to use. Use "(default)" for the default database. You can view your available
Firestore databases at https://console.cloud.google.com/firestore/databases.) eu-testing
# Omitting many more parameters for brevity
✔ Wrote configuration info to firebase.json
✔ functions: Function kit firestore-bigquery-export successfully installed.
i functions: At the first deploy, the following functions will be created in your project:
- kit-firestore-bigquery-export-fsexportbigquery
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i functions: At the first deploy, the following Task Queues will be created in your project:
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i functions: At the first deploy, the following APIs will be enabled in your project:
- bigquery.googleapis.com
- cloudtasks.googleapis.com
i functions: At the first deploy, the following roles will be granted to the kit service account:
- BigQuery Data Editor
- BigQuery User
- Cloud Datastore User
- Eventarc Event Receiver
- roles/run.invoker
⚠ functions: Please review the changes above. If you do not want them applied to your project, uninstall this kit before running firebase deploy.
Changing default global options
To configure the global
options
for your kit instance, modify the index.ts file located at
function-kits/<your-kit-id>/source/src/index.ts.
If you want the defaults to be shared across all instances of the kit, set them
directly in index.ts. Otherwise, create
parameters that are set per instance,
following the examples and instructions documented in index.ts.
Deploying the kit
To deploy your function kit, run:
firebase deploy --only functions:<kit-instance-id>
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!
Installing and deploying the kit performs the following actions:
- Creates
function-kits/firestore-bigquery-export/source, which contains the kit source including a basicindex.tsfile that imports and exports the kit package while setting up a parameter that lets you pick a different location for each instance of the kit. - Creates
function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id>and populates it with the configuration data entered for the function. If future updates add new parameters, you're prompted on the next deployment. - Creates the required Google Cloud resources to run this kit, including a service account with specific IAM roles, functions, Eventarc triggers, and Cloud Tasks queues.
If you have multiple instances of the kit in the same project, you can repeat these commands to create and deploy new instances of the same kit. You can also deploy a single kit instance to multiple Firebase projects with different configurations (for example, a staging project and a production project). To learn more about advanced setups, see Advanced migrations.
Uninstalling a kit
To remove the kit and all of its instances, run:
firebase functions:kits:uninstall --kit <kit-id>
This deletes all instances and their configurations and removes the kit source from disk.
To remove only a single instance of the kit, run:
firebase functions:kits:uninstall --instance <kit-instance-id>
If you only have one instance of the kit, this uninstalls the entire kit.
Updating a kit configuration
During installation or your first deployment, you're prompted to configure all
parameters for your kit (unless you migrated a configuration from an extension).
These parameters are stored in the .env file in your kit instance
configuration directory. For example, if you have a kit instance named
firestore-bigquery-export in project my-project, the .env file is located
at
function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project.
It looks like the following:
DATASET_LOCATION=us
BIGQUERY_PROJECT_ID=my-project
DATABASE=eu-testing
DATABASE_REGION=eur3
COLLECTION_PATH=posts
WILDCARD_IDS=false
DATASET_ID=firestore_export
TABLE_ID=posts
TABLE_PARTITIONING=NONE
TIME_PARTITIONING_FIELD=
TIME_PARTITIONING_FIRESTORE_FIELD=
TIME_PARTITIONING_FIELD_TYPE=omit
CLUSTERING=
MAX_DISPATCHES_PER_SECOND=100
VIEW_TYPE=view
MAX_STALENESS=
REFRESH_INTERVAL_MINUTES=
BACKUP_COLLECTION=
TRANSFORM_FUNCTION=
USE_NEW_SNAPSHOT_QUERY_SYNTAX=no
EXCLUDE_OLD_DATA=no
KMS_KEY_NAME=
MAX_ENQUEUE_ATTEMPTS=3
LOG_LEVEL=info
FUNCTION_DEFAULT_REGION=us-west1
If you know the configuration value you want to change, you can edit it directly
in the .env file. If you prefer to use the interactive prompt that runs during
installation and deployment, remove the parameters you want to change from the
.env file and redeploy the kit instance. You're prompted to enter those
parameters during deployment.
For example, if you delete the line COLLECTION_PATH=posts and deploy, you're
prompted for it during deployment:
i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export-d9cd/.env.ajp-testing
Prompting for parameters for codebase firestore-bigquery-export:
Collection path: What is the path of the collection that you would like to export? You may use {wildcard} notation to match a subcollection of all documents in a collection (for example: chatrooms/{chatid}/posts). Parent Firestore Document IDs from {wildcards} can be returned in path_params as a JSON formatted string.
? Enter a string value for Collection path: (posts)
Maintaining and upgrading a function kit
Publishers may update their npm packages over time to fix bugs, add features, update dependencies, or address security vulnerabilities. We recommend staying up to date on these releases and installing updates—especially those that address security vulnerabilities.
The functions:kits:install command creates a codebase that installs a kit as
an npm package and exports all of its functions for each instance of your kit.
To upgrade a kit, update the package version and then redeploy each instance of
your kit to apply the changes.
Determining if a kit has updates
Go to the source directory of your kit at
function-kits/<your-kit-id>/source. From this source directory, run the
following command to get a report on all outdated npm packages, including your
function kit and the Cloud Functions SDK:
npm outdated
If you already use a tool to identify dependencies that need updating, such as Dependabot for GitHub, we recommend integrating your kit directory into that workflow.
Updating a kit
To update the kit and its dependencies to the latest non-breaking version (excluding major version updates that might contain breaking changes), run:
npm update --save
If you only want to update the function kit package and no other packages, pass
the package name to npm update:
npm update <package-name> --save
To upgrade a package to the latest major version (which can introduce breaking changes), run:
npm update --save <npm-package-name>@latest
Review the package documentation and release notes to see what has changed and whether you need to take any additional steps before or after deployment to prevent breaking changes.
Deploying updated instances
Running npm update only updates your local source code. To update your running
functions in the cloud, redeploy them. You can redeploy all functions in your
project, including all function kits, by running:
firebase deploy --only functions
Undoing a migration
To undo a migration, reinstall the extension first. You can use the kit's .env
file to find the configuration values needed during installation.
After the extension is deployed, uninstall the kit instance (this uninstalls the entire kit if it's the last remaining instance):
firebase functions:kits:uninstall --instance <kit-instance-id> --project <project-id>
Saving extension configurations for a future migration
After March 31, 2027, you'll be unable to fetch an existing extension configuration. If you're unable to migrate before March 31, 2027, we strongly recommend saving your extension in case you decide to migrate after this date.
Get a list of your extension instance IDs:
You can use the
ext:listCLI command to get a list of all extension instances in your Firebase project:firebase ext:list --project <project-id>Worked example:
firebase ext:list --project my-project» firebaselocal ext:list i extensions: ensuring required API firebaseextensions.googleapis.com is enabled... i extensions: list of extensions installed in ajp-testing: ┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐ │ Extension │ Publisher │ Instance ID │ State │ Version │ Your last update │ Replacement Kit │ ├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤ │ firebase/firestore-bigquery-export │ firebase │ firestore-bigquery-export-zbrp │ ACTIVE │ 0.3.3 │ 2026-09-06 22:31:04 │ @firebase-function-kits/firestore-bigquery-export │ ├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤ │ firebase/firestore-bigquery-export │ firebase │ firestore-bigquery-export │ ACTIVE │ 0.3.2 │ 2026-06-03 17:41:24 │ @firebase-function-kits/firestore-bigquery-export │ └────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘ ⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshootingThe
ext:listcommand also has a JSON output format, and if you have the utility jq installed, you can use it to get a list of all instance IDs for a project:firebase ext:list --json --project <project-id> | jq -r '.result[].instanceId'Worked example:
firebase ext:list --json --project my-project | jq -r '.result[].instanceId'Output:
firestore-bigquery-export-zbrp firestore-bigquery-exportExport the configuration for each instance:
For each instance, you can save its configuration on disk by executing the following export command:
firebase ext:export --mode functions --project <project-id> --instance <your-instance-id>Worked example:
firebase ext:export --mode functions --project my-project --instance firestore-bigquery-exportOutput:
i extensions: ensuring required API firebaseextensions.googleapis.com is enabled... i functions: Saving exported extensions config as a Function Kits .env file i functions: Created new local file firestore-bigquery-export/.env.testing to store param values. We suggest explicitly adding or excluding this file from version control. i functions: Loaded environment variables from firestore-bigquery-export/.env.testing i functions: Loaded environment variables from firestore-bigquery-export/.env.testing i functions: Writing new parameter values to disk: firestore-bigquery-export/.env.testingOn disk, you'll find an export of this extension instance at a location like
<instance-id>/.env.<project-id>. In this example, it's located atfirestore-bigquery-export/.env.my-project.You can repeat this process once per instance, and it creates a set of
.envfiles with all your extension instance configurations that can be reused later as part of a migration.Move the exported
.envfiles to a better location:The exported
.envfiles from your extensions were placed directly into your Firebase project, but aren't needed on a day-to-day basis if you haven't migrated to function kits. You can move them from your project to any other appropriate storage location until you need them in the future or choose to delete them.