Prácticas recomendadas posteriores a la migración

Después de migrar de Firebase Extensions a un kit de funciones, administras las instancias del kit como Cloud Functions estándar de 2ª gen. en tu proyecto de Firebase. En esta guía, se explica cómo instalar kits de funciones nuevos directamente desde npm sin migrar una extensión existente, actualizar los parámetros del kit y las opciones globales, actualizar las versiones de los paquetes de npm a medida que los publicadores lanzan actualizaciones y revertir una migración si es necesario.

Usa un kit de funciones de un paquete de npm sin migrar

Si no migras desde una extensión, el uso de un kit de funciones consta de dos partes:

Cómo instalar el kit

Puedes instalar un kit de funciones con el siguiente comando de la CLI:

firebase functions:kits:install --package <npm-package-name>

Ejemplo práctico:

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.

Cambia las opciones globales predeterminadas

Para configurar las opciones globales de tu instancia del kit, modifica el archivo index.ts ubicado en function-kits/<your-kit-id>/source/src/index.ts.

Si deseas que los valores predeterminados se compartan en todas las instancias del kit, configúralos directamente en index.ts. De lo contrario, crea parámetros que se configuren por instancia, siguiendo los ejemplos y las instrucciones que se documentan en index.ts.

Implementa el kit

Para implementar tu kit de funciones, ejecuta lo siguiente:

firebase deploy --only functions:<kit-instance-id>

Ejemplo práctico:

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

Resultado:

=== 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!

Cuando instalas e implementas el kit, se realizan las siguientes acciones:

  • Crea function-kits/firestore-bigquery-export/source, que contiene la fuente del kit, incluido un archivo index.ts básico que importa y exporta el paquete del kit mientras se configura un parámetro que te permite elegir una ubicación diferente para cada instancia del kit.
  • Crea function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id> y lo propaga con los datos de configuración ingresados para la función. Si las actualizaciones futuras agregan parámetros nuevos, se te solicitará que los configures en la próxima implementación.
  • Crea los recursos de Google Cloud necesarios para ejecutar este kit, incluida una cuenta de servicio con roles de IAM, funciones, activadores de Eventarc y listas de tareas en cola de Cloud Tasks específicos.

Si tienes varias instancias del kit en el mismo proyecto, puedes repetir estos comandos para crear e implementar instancias nuevas del mismo kit. También puedes implementar una sola instancia de kit en varios proyectos de Firebase con diferentes parámetros de configuración (por ejemplo, un proyecto de etapa de pruebas y otro de producción). Para obtener más información sobre las configuraciones avanzadas, consulta Migraciones avanzadas.

Cómo desinstalar un kit

Para quitar el kit y todas sus instancias, ejecuta lo siguiente:

firebase functions:kits:uninstall --kit <kit-id>

Esto borra todas las instancias y sus configuraciones, y quita la fuente del kit del disco.

Para quitar solo una instancia del kit, ejecuta lo siguiente:

firebase functions:kits:uninstall --instance <kit-instance-id>

Si solo tienes una instancia del kit, se desinstalará todo el kit.

Actualiza la configuración de un kit

Durante la instalación o la primera implementación, se te solicitará que configures todos los parámetros de tu kit (a menos que hayas migrado una configuración desde una extensión). Estos parámetros se almacenan en el archivo .env del directorio de configuración de la instancia del kit. Por ejemplo, si tienes una instancia de kit llamada firestore-bigquery-export en el proyecto my-project, el archivo .env se encuentra en function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project.

Se verá de la siguiente manera:

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

Si conoces el valor de configuración que deseas cambiar, puedes editarlo directamente en el archivo .env. Si prefieres usar el mensaje interactivo que se ejecuta durante la instalación y la implementación, quita los parámetros que quieras cambiar del archivo .env y vuelve a implementar la instancia del kit. Se te pedirá que ingreses esos parámetros durante la implementación.

Por ejemplo, si borras la línea COLLECTION_PATH=posts y realizas la implementación, se te solicitará durante la implementación:

i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export-d9cd/.env.my-project
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)

Mantenimiento y actualización de un kit de funciones

Los publicadores pueden actualizar sus paquetes de npm con el tiempo para corregir errores, agregar funciones, actualizar dependencias o abordar vulnerabilidades de seguridad. Te recomendamos que te mantengas al tanto de estas versiones y que instales las actualizaciones, en especial las que abordan vulnerabilidades de seguridad.

El comando functions:kits:install crea una base de código que instala un kit como un paquete de npm y exporta todas sus funciones para cada instancia de tu kit. Para actualizar un kit, actualiza la versión del paquete y, luego, vuelve a implementar cada instancia de tu kit para aplicar los cambios.

Cómo determinar si un kit tiene actualizaciones

Ve al directorio source de tu kit en function-kits/<your-kit-id>/source. Desde este directorio source, ejecuta el siguiente comando para obtener un informe de todos los paquetes de npm desactualizados, incluidos el kit de funciones y el SDK de Cloud Functions:

npm outdated

Si ya usas una herramienta para identificar las dependencias que se deben actualizar, como Dependabot para GitHub, te recomendamos que integres el directorio del kit en ese flujo de trabajo.

Cómo actualizar un kit

Para actualizar el kit y sus dependencias a la versión más reciente que no sea de cambio rotundo (sin incluir las actualizaciones de versiones principales que puedan contener cambios rotundos), ejecuta lo siguiente:

npm update --save

Si solo quieres actualizar el paquete de Function Kit y ningún otro, pasa el nombre del paquete a npm update:

npm update <package-name> --save

Para actualizar un paquete a la versión principal más reciente (que puede introducir cambios rotundos), ejecuta lo siguiente:

npm update --save <npm-package-name>@latest

Revisa la documentación del paquete y las notas de la versión para ver qué cambió y si necesitas realizar pasos adicionales antes o después de la implementación para evitar cambios rotundos.

Implementa instancias actualizadas

Ejecutar npm update solo actualiza tu código fuente local. Para actualizar las funciones que se ejecutan en la nube, vuelve a implementarlas. Para volver a implementar todas las funciones de tu proyecto, incluidos todos los kits de funciones, ejecuta lo siguiente:

firebase deploy --only functions

Cómo deshacer una migración

Para deshacer una migración, primero vuelve a instalar la extensión. Puedes usar el archivo .env del kit para encontrar los valores de configuración necesarios durante la instalación.

Después de implementar la extensión, desinstala la instancia del kit (esto desinstala todo el kit si es la última instancia restante):

firebase functions:kits:uninstall --instance <kit-instance-id> --project <project-id>

Guarda la configuración de las extensiones para una migración futura

Después del 31 de marzo de 2027, no podrás recuperar una configuración de extensión existente. Si no puedes migrar antes del 31 de marzo de 2027, te recomendamos guardar la extensión en caso de que decidas migrar después de esta fecha.

  1. Obtén una lista de los IDs de tus instancias de extensiones:

    Puedes usar el comando de la CLI de ext:list para obtener una lista de todas las instancias de extensión en tu proyecto de Firebase:

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

    Ejemplo práctico:

    firebase ext:list --project my-project

    » firebase ext:list
i  extensions: ensuring 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.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-troubleshooting

    El comando ext:list también tiene un formato de salida JSON y, si tienes instalada la utilidad jq, puedes usarla para obtener una lista de todos los IDs de instancia de un proyecto:

    firebase ext:list --json --project <project-id> | jq -r '.result[].instanceId'

    Ejemplo práctico:

    firebase ext:list --json --project my-project | jq -r '.result[].instanceId'

    Resultado:

    firestore-bigquery-export-zbrp
firestore-bigquery-export

  2. Exporta la configuración de cada instancia:

    Para cada instancia, puedes guardar su configuración en el disco ejecutando el siguiente comando de exportación:

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

    Ejemplo práctico:

    firebase ext:export --mode functions --project my-project --instance firestore-bigquery-export

    Resultado:

    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.testing

    En el disco, encontrarás una exportación de esta instancia de extensión en una ubicación como <instance-id>/.env.<project-id>. En este ejemplo, se encuentra en firestore-bigquery-export/.env.my-project.

    Puedes repetir este proceso una vez por instancia, y se creará un conjunto de archivos .env con todas las configuraciones de instancias de extensiones que se pueden reutilizar más adelante como parte de una migración.

  3. Mueve los archivos .env exportados a una ubicación más adecuada:

    Los archivos .env exportados de tus extensiones se colocaron directamente en tu proyecto de Firebase, pero no son necesarios para el día a día si no migraste a los kits de funciones. Puedes moverlos de tu proyecto a cualquier otra ubicación de almacenamiento adecuada hasta que los necesites en el futuro o decidas borrarlos.