Migra las Extensiones de Firebase a kits de funciones

En esta guía, se muestra cómo migrar tus extensiones del entorno Firebase Extensions obsoleto a un kit de funciones que puedes instalar e implementar en tu propio Cloud Functions para la base de código de Firebase (2ª gen.).

Firebase Extensions administró todos los aspectos de la creación, actualización y eliminación de extensiones. Los kits de funciones empaquetan las capacidades de las extensiones como Cloud Functions for Firebase típicos de 2ª gen. Dado que los kits de funciones son Cloud Functions estándar, puedes crearlos, actualizarlos, borrarlos y solucionar problemas relacionados con ellos usando la CLI de Firebase dentro de tu proyecto de Firebase. Esta guía te prepara para administrar tus funciones ahora y adoptar las actualizaciones a medida que estén disponibles.

A lo largo de esta guía, se usa la extensión Stream Cloud Firestore to BigQuery (firestore-bigquery-export) como ejemplo para mostrarte los comandos y el resultado de los comandos para cada paso de la migración.

Determina tu ruta de migración

Firebase alienta a todos los publicadores de Firebase Extensions a crear reemplazos para sus extensiones como kits de funciones publicados en npm. Puedes verificar si hay un reemplazo del kit de funciones disponible para tus extensiones de diferentes maneras:

  • Ve a la página Extensiones de la consola de Firebase de tu proyecto. Cada extensión que instalaste indica si tiene un reemplazo del kit de funciones disponible.

  • Ejecuta firebase ext:list dentro de tu proyecto Firebase en una terminal para mostrar cuáles de tus extensiones instaladas tienen reemplazos oficiales:

    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

Si hay un reemplazo oficial del kit de funciones disponible para tu extensión, puedes migrarla con la sección Migrate to function kits on npm.

Si no encuentras un reemplazo publicado, puedes bifurcar el código de la extensión y crear tu propio reemplazo, ya que todas las extensiones son de código abierto. Para ello, sigue la guía Migra a un kit de funciones creado por ti.

Selecciona la ruta de migración: Migra a kits de funciones en npm Migra a un kit de funciones creado por ti

Migra a kits de funciones en npm

Verifica si hay limitaciones conocidas de la migración

Antes de comenzar a migrar una instancia de extensión, verifica si tu configuración usa alguna de las siguientes funciones que requieren una solución alternativa o que aún no son compatibles con los kits de funciones:

  • Los repositorios de Docker personalizados y las claves de KMS requieren una solución manual Cloud Functions for Firebase no admite parámetros del sistema de reemplazo para configurar un repositorio de Docker personalizado o una clave de encriptación administrada por el cliente (clave de KMS). Si tu extensión configura alguno de estos parámetros, consulta la solución alternativa de las preguntas frecuentes.

Antes de comenzar

Debes configurar la CLI de Firebase y inicializar un proyecto de Firebase. Cuando uses la CLI, asegúrate de usar la versión >= 15.32.0 de firebase-tools, que tiene los nuevos comandos de migración y del kit de funciones.

Roles y permisos de la cuenta obligatorios

Según lo que deba crear y configurar la CLI de Firebase durante la migración, la cuenta que uses para autenticarte con Firebase y Google Cloud debe tener los siguientes roles:

  • roles/firebaseextensions.editor
  • roles/cloudbuild.builds.editor
  • roles/artifactregistry.writer
  • roles/run.developer
  • roles/iam.serviceAccountUser
  • roles/iam.serviceAccountCreator
  • roles/cloudfunctions.admin (si necesitas hacer setIamPermissions para los extremos públicos)
  • roles/secretmanager.admin (si se usan secretos)
  • roles/serviceusage.serviceUsageAdmin (si necesitas habilitar APIs nuevas)

Te recomendamos que uses una cuenta que ya haya instalado extensiones y funciones implementadas, ya que la mayoría de estos permisos ya se habrán otorgado. Si tu cuenta de migración necesita más roles, sigue las instrucciones de IAM de Google Cloud para agregarlos.

Elige un flujo de trabajo de la CLI

Para migrar de una instancia de extensión a un kit de funciones disponible en npm, elige una de las siguientes opciones:

  • (Recomendado) Migra con el comando de la CLI de ext:migrate. Este comando implementa el reemplazo del kit de funciones antes de desinstalar la extensión que reemplaza.
  • Migra con los comandos de la CLI de los kits de funciones. Puedes usar comandos separados para actualizar la extensión, instalar un kit de funciones, configurarlo como la extensión, implementar el kit y desinstalar la extensión. Esto proporciona más flexibilidad para reordenar comandos o realizar trabajo adicional entre los pasos.

Migra con ext:migrate

Una vez por instancia de extensión, inicia una migración ejecutando el siguiente comando:

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

Este comando te guía por los siguientes pasos:

  1. Seleccionar una extensión para migrar que tenga un reemplazo oficial de kit de funciones disponible
  2. Seleccionar una instancia específica de esa extensión
  3. Actualizar la extensión a su versión más reciente, si es necesario
  4. Instalar el kit de funciones y configurar una instancia de forma idéntica a como se configura la instancia de extensión
  5. Se implementa el kit de funciones.
  6. Verificar que el kit de funciones se haya implementado correctamente y que se hayan ejecutado todos los hooks del ciclo de vida, si los hay
  7. Se desinstala la instancia de extensión.

Si conoces la extensión o la instancia de extensión específicas que deseas migrar, especifícalas con las siguientes marcas de línea de comandos:

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

# or

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

Si conoces el paquete específico al que deseas migrar, en especial si no es un paquete de reemplazo oficial que Google haya incluido en la lista, especifícalo con la marca --package:

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

Verifica la implementación de un kit de funciones

Para verificar que el firebase deploy del kit no haya tenido errores, consulta los registros de implementación para ver si se activó algún gancho de ciclo de vida. Las extensiones populares, como Stream Cloud Firestore a BigQuery, usan hooks de ciclo de vida. El siguiente es un ejemplo de cómo se ve un hook de ciclo de vida cuando se activa:

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

Estos mensajes de registro confirman lo siguiente:

  • Se encontró y ejecutó un hook de ciclo de vida.
  • Se puso en cola una tarea en la lista de tareas en cola asociada del gancho de ciclo de vida.
  • Se proporcionó un vínculo a Cloud Logging para que puedas validar que la tarea se completó sin errores.

Sigue el vínculo de registros a la consola de Google Cloud para validar que no haya errores en los registros y que el evento de la lista de tareas en cola se haya procesado correctamente. Si el evento de ciclo de vida no se ejecutó correctamente, puedes volver a activarlo con el siguiente comando:

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

Si es la primera vez que implementas una instancia de Function Kit, ejecuta el siguiente comando:

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

Si en algún momento durante la validación decides que quieres detener o deshacer esta migración, puedes desinstalar el kit siguiendo las instrucciones que se indican en Cómo desinstalar la extensión.

Revisa el README del kit de funciones

Es posible que algunos kits requieran trabajo adicional más allá de lo que manejan automáticamente los kits de funciones. Revisa la README del kit que estás instalando y sigue las instrucciones adicionales.

Migra con la CLI de los kits de funciones

Antes de comenzar, identifica y anota el ID de instancia de la extensión que deseas migrar a un kit y el nombre del paquete npm de su kit de reemplazo. Puedes encontrar ambos valores con el resultado de firebase ext:list. Consulta Cómo determinar tu ruta de migración para ver un ejemplo del uso de ext:list.

1. Actualiza la instancia de extensión a la versión más reciente

Debes actualizar tu extensión a la versión más reciente para minimizar la diferencia entre la instancia de extensión y el kit de reemplazo. Si tu extensión no se actualiza, es posible que haya cambios significativos y que interrumpan la compatibilidad entre tu instancia de extensión y su reemplazo de kit. Es posible que la configuración exportada no coincida con lo que espera el kit debido a los cambios de parámetros entre versiones.

Usa una de las siguientes opciones para actualizar tu extensión, según dónde se haya instalado:

  • Desde la consola de Firebase
  • Desde la CLI de Firebase, usa el siguiente comando:
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

Si omites este paso, la CLI te solicitará que actualices la configuración cuando exportes la configuración si tu extensión no está en la versión más reciente.

2. Revisa e instala la instancia del kit de reemplazo de la función

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

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

Cuando elijas un ID de instancia para tu kit durante la instalación, asegúrate de anotarlo para usarlo más adelante en las instrucciones de migración.

Una vez que se instala el kit, se crea un directorio nuevo dentro de tu proyecto Firebase con una ubicación como function-kits/<kit-name>/source que contiene el paquete npm con el kit que reemplaza tu extensión y un archivo index.ts básico que exporta esas funciones para que Firebase implemente y establezca la configuración personalizada.

Revisa el archivo README del kit y sigue las instrucciones adicionales que se indiquen allí.

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

Ejemplo sobre el que se trabajó:

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

3. Configura la instancia del kit de funciones de forma idéntica a la extensión

Debes personalizar esta instancia del kit con una configuración idéntica a la de la extensión que reemplaza. Puedes exportar la configuración de la instancia de tu extensión a un archivo .env, que almacena datos de configuración de parámetros, variables de entorno y referencias a secretos para todos los Cloud Functions, incluidos los kits. Para exportarlo directamente al archivo de configuración de tu kit, ejecuta el siguiente comando:

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

Al final de este paso, la información de configuración de esta instancia se almacena en un archivo .env específico del proyecto en el directorio de configuración de la instancia, como el siguiente: function-kits/<kit-name>/config-<instance-id>/.env.<project-id>

4. Implementa y verifica el reemplazo del kit

Ahora que el kit está instalado y disponible como un conjunto de funciones, puedes implementar el reemplazo del kit. Los kits de funciones funcionan como las funciones estándar, en las que cada instancia del kit actúa como una base de código independiente para organizar tus funciones. Puedes elegir implementar todas tus funciones o solo una instancia de kit específica. Cuando migres una sola instancia de extensión, implementa solo esa instancia del kit.

Si tu kit usa parámetros nuevos que no estaban presentes en la instancia de extensión desde la que migraste, la CLI de Firebase te los solicitará al comienzo del proceso de implementación. Esto no se espera en este ejemplo práctico de una extensión firestore-bigquery-export actualizada, pero muchos kits solicitan un parámetro nuevo para cualquier fuente de activación de eventos que use el kit. Como parte de esta migración, los kits actualizados usan funciones de 2ª gen. en los casos en que las extensiones usaban funciones de 1ª gen. En la 2ª gen., las funciones se ubican cerca de sus fuentes de eventos y se agregan como un parámetro adicional. En futuras actualizaciones, si se agregan parámetros nuevos, la CLI te solicitará que los ingreses en la próxima implementación.

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!

Para verificar que el firebase deploy del kit no haya tenido errores, consulta los registros de implementación para ver si se activó algún gancho de ciclo de vida. Las extensiones populares, como Stream Cloud Firestore a BigQuery, usan hooks de ciclo de vida. El siguiente es un ejemplo de cómo se ve un hook de ciclo de vida cuando se activa:

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

Estos mensajes de registro confirman lo siguiente:

  • Se encontró y ejecutó un hook de ciclo de vida.
  • Se puso en cola una tarea en la lista de tareas en cola asociada del gancho de ciclo de vida.
  • Se proporcionó un vínculo a Cloud Logging para que puedas validar que la tarea se completó sin errores.

Sigue el vínculo de registros a la consola de Google Cloud para validar que no haya errores en los registros y que el evento de la lista de tareas en cola se haya procesado correctamente. Si el evento de ciclo de vida no se ejecutó correctamente, puedes volver a activarlo con el siguiente comando:

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

Si es la primera vez que implementas una instancia de Function Kit, ejecuta el siguiente comando:

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

Si en algún momento durante la validación decides que quieres detener o deshacer esta migración, puedes desinstalar el kit siguiendo las instrucciones que se indican en Cómo desinstalar la extensión.

5. Desinstala la extensión

Cuando hayas verificado el kit de funciones implementado, puedes desinstalar la extensión para no duplicar su comportamiento una vez para el kit y otra para la extensión. Puedes desinstalar todas las extensiones de la CLI de Firebase, independientemente de cómo las hayas instalado, si pasas la marca --immediate:

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

Ejemplo sobre el que se trabajó:

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

Resultado:

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

Migraciones avanzadas

Puedes tener extensiones en varios proyectos de Firebase que desees administrar con una sola base de código. Por ejemplo, si implementas la misma infraestructura en un entorno testing y en un entorno production, cada uno de los cuales tiene una instancia de documents Cloud Firestore que exportas a BigQuery, es posible que tengas dos instancias de la extensión firestore-bigquery-export instaladas:

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

Si migraste estas dos instancias de extensión a dos instancias del kit de funciones en una sola base de código cuando trabajabas con la CLI de Firebase y realizaste la implementación con firebase deploy --project testing y firebase deploy --project production, cada implementación crearía dos instancias en los entornos de testing y production.

En su lugar, reemplaza las dos instancias de extensión por una instancia de Function Kit de firestore-bigquery-export implementada en varios proyectos, en la que cada proyecto tenga su propia configuración. El directorio de configuración de la instancia debería verse de la siguiente manera:

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

Cada implementación en testing y production crea una instancia de tu kit con la configuración correspondiente. Los comandos de la CLI existentes crean esta configuración siempre que pases la marca --project en cada invocación de ext:migrate o functions:kits:install.

Ejemplo sobre el que se trabajó:

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

Ahora tienes una sola instancia del kit configurada para implementarse en tus proyectos testing y production con sus respectivas configuraciones. Si creas una instancia en el proyecto testing y ejecutas el comando functions:kits:install para el mismo paquete en el proyecto production, se te solicitará que reutilices la instancia configurada para testing o que instales una segunda instancia.