Prácticas recomendadas posteriores a la migración

Después de migrar de Firebase Extensions a un kit de funciones, administrarás tus 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.

Cómo usar un kit de funciones de un paquete npm sin migrar

Si no migras desde una extensión, usar 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 sobre el que se trabajó:

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.

Cómo cambiar las opciones globales predeterminadas

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

Si quieres 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 el siguiente comando:

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

Ejemplo sobre el que se trabajó:

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!

La instalación y la implementación del kit 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 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 agregues 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 específicos, funciones, activadores de Eventarc y colas de Cloud Tasks.

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

Cómo desinstalar un kit

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

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 el siguiente comando:

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 del 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.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)

Mantenimiento y actualización de un kit de funciones

Con el tiempo, los publicadores pueden actualizar sus paquetes de npm 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 npm y exporta todas sus funciones para cada instancia del kit. Para actualizar un kit, actualiza la versión del paquete y, luego, vuelve a implementar cada instancia del 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 sobre todos los paquetes npm desactualizados, incluido tu kit de funciones y el SDK de Cloud Functions:

npm outdated

Si ya usas una herramienta para identificar las dependencias que necesitan actualización, como Dependabot para GitHub, te recomendamos que integres el directorio de tu 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 genere errores (sin incluir las actualizaciones de versiones principales que podrían contener cambios que generen errores), ejecuta lo siguiente:

npm update --save

Si solo deseas actualizar el paquete del kit de funciones y ningún otro paquete, 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 que interrumpen la compatibilidad), 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 que generen errores.

Implementa instancias actualizadas

Ejecutar npm update solo actualiza tu código fuente local. Para actualizar tus funciones en ejecución en la nube, vuelve a implementarlas. Puedes volver a implementar todas las funciones de tu proyecto, incluidos todos los kits de funciones, con el siguiente comando:

firebase deploy --only functions

Cómo deshacer una migración

Para deshacer una migración, primero reinstala 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>

Cómo guardar la configuración de extensiones para una migración futura

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

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

    Puedes usar el comando de CLI 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 sobre el que se trabajó:

    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-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 instancias de un proyecto:

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

    Ejemplo sobre el que se trabajó:

    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 sobre el que se trabajó:

    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 extensión que se pueden reutilizar más adelante como parte de una migración.

  3. Mueve los archivos .env exportados a una mejor ubicación:

    Los archivos .env exportados de tus extensiones se colocaron directamente en tu proyecto de Firebase, pero no son necesarios a diario 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.