Administra la configuración del proyecto con el manifiesto de extensiones

Un manifiesto de extensiones es una lista de instancias de extensiones con su configuración. Con el manifiesto, puedes hacer lo siguiente:

  • Compartir la configuración de tus extensiones con otras personas
  • Copiar la configuración de las extensiones entre diferentes proyectos (por ejemplo, desde el proyecto en etapa de pruebas hasta el que se encuentra en producción)
  • Implementar todas tus extensiones a la vez
  • Probar el funcionamiento de las extensiones con tu app mediante Firebase Local Emulator Suite
  • Confirmar la configuración de las extensiones para el control de fuentes
  • Incluir extensiones en tu canalización de CI/CD

Un manifiesto de extensiones consta de dos partes:

  • La sección extensions de firebase.json, que es un mapa del ID de instancia para la referencia de la versión de la extensión. Por ejemplo:

    {
     "extensions": {
       "my-bigquery-extension": "firebase/firestore-bigquery-export@^0.1.18",
       "my-image-resizer": "firebase/storage-resize-images@^0.1.22",
     }
    }
    
  • Archivos .env que contengan la configuración de cada una de las instancias de extensiones en el subdirectorio extensions/ del directorio del proyecto de Firebase. Por ejemplo, una instancia de storage-resize-images podría tener un archivo .env como el siguiente:

    IMAGE_TYPE=jpeg
    LOCATION=us-central1
    IMG_BUCKET=${param:PROJECT_ID}.appspot.com
    IMG_SIZES=100x100
    DELETE_ORIGINAL_FILE=false

Crea un manifiesto de extensiones

Estas son las tres maneras de crear un manifiesto de extensiones:

  • Administrar los manifiestos de extensiones con Firebase CLI
  • Exportar la configuración de extensiones de un proyecto
  • Editar los archivos de manifiesto de forma manual

Los dos primeros métodos se explican a continuación.

Administra los manifiestos de extensiones con Firebase CLI

Puedes ejecutar la mayoría de los comandos ext: de Firebase CLI con la opción --local para actualizar el manifiesto de extensiones sin cambiar la configuración actual del proyecto.

Por ejemplo:

firebase ext:install --local firebase/firestore-bigquery-export

Si ejecutas el comando anterior, se te pedirá que configures la versión más reciente de la extensión firebase/firestore-bigquery-export y que guardes la configuración en el manifiesto, pero esta no se implementará en tu proyecto.

Aquí encontrarás otros ejemplos de comandos que modifican el manifiesto de extensiones:

# ext:configure changes the params for an extension instance in your extensions manifest
$ firebase ext:configure my-bigquery-extension --local

# ext:update --local updates an instance in your extensions manifest
# to the latest version of that extension
$ firebase ext:update my-bigquery-extension --local

# You can also specify a version if you don't want to update to the latest version
$ firebase ext:update my-bigquery-extension firebase/firestore-bigquery-export@0.1.10 --local 

# ext:uninstall --local removes an instance from your extensions manifest
$ firebase ext:uninstall my-bigquery-extension --local

Exporta la configuración de extensiones de un proyecto

Para guardar la configuración actual de extensiones de un proyecto en el manifiesto, haz lo siguiente:

  1. Si aún no lo has hecho, configura Firebase CLI.
  2. Desde un símbolo del sistema de shell, cambia al directorio del proyecto (este contiene el archivo firebase.json).
  3. Ejecuta el comando ext:export:
    firebase ext:export

El comando ext:export agregará una sección extensions al archivo firebase.json. Además, el comando ext:export crea un directorio extensions que contiene un archivo .env para cada instancia de extensión que instalaste. Estos archivos incluyen los parámetros de configuración de cada instancia.

Prueba una configuración de extensiones con Firebase Local Emulator Suite

Cuando hayas agregado algunas instancias de extensiones al manifiesto, puedes probarlas de forma local con Local Emulator Suite.

  1. Instala y configura Local Emulator Suite.

  2. Inicia Local Emulator Suite:

    • Para ejecutar Emulator Suite de forma interactiva, ejecuta firebase emulators:start
    • Para iniciar Emulator Suite y ejecutar una secuencia de comandos de prueba, usa lo siguiente: firebase emulators:exec my-test.sh

Si tienes instancias de extensiones en el manifiesto, Local Emulator Suite descargará el código fuente de esas extensiones en ~/.cache/firebase/extensions. Cuando se hayan descargado, se iniciará Local Emulator Suite, y podrás activar cualquiera de las funciones activadas en segundo plano de las extensiones y conectar tu app a Emulator Suite para probar su integración en la app.

Implementa una configuración de extensiones en un proyecto

Cuando hayas agregado algunas instancias de extensiones al manifiesto, puedes implementarlo en un proyecto con Firebase CLI. Cuando realizas la implementación con un manifiesto de extensiones, debes instalar, actualizar y configurar todas las instancias de extensiones del manifiesto en un proyecto a la vez.

Sigue estos pasos para implementar un manifiesto de extensiones:

  1. Desde un mensaje de shell, cámbiate al directorio que contiene la configuración de las extensiones guardadas. Este es el directorio que contiene firebase.json. Si acabas de ejecutar ext:export, ya estás en el directorio correcto.
  2. Ejecuta el comando deploy. Si quieres implementar las extensiones en un proyecto distinto del actual, también especifica --project=:
    firebase deploy --only extensions –-project=YOUR_PROJECT_ID

El comando deploy validará la configuración de cada instancia, te preguntará si quieres borrar alguna instancia de extensión del proyecto de destino que no aparezca en firebase.json y, luego, implementará todas las instancias de extensión.

Parámetros de configuración de extensiones específicos del proyecto

Los parámetros de configuración de las extensiones guardadas se pueden utilizar para implementarlos en varios proyectos diferentes; por ejemplo, un proyecto de etapa de pruebas y otro de producción. Cuando lo hagas, es posible que algunos valores de parámetros deban ser diferentes para cada proyecto. Esto es posible gracias a los archivos .env específicos del proyecto:

  • Coloca valores de parámetros que difieran entre los proyectos en extensions/EXTENSION_INSTANCE_ID.env.YOUR_PROJECT_ID.
  • Coloca los valores de parámetros compartidos en extensions/EXTENSION_INSTANCE_ID.env.

A veces, es recomendable que uses un valor de parámetro diferente cuando emules tus extensiones. Por ejemplo, puedes proporcionar una clave de API de prueba en lugar de una de producción. Coloca estos parámetros en un archivo .local:

  • Coloca los parámetros no secretos que quieres usar durante la emulación en extensions/EXTENSION_INSTANCE_ID.env.local.
  • Coloca los valores de los parámetros secretos en extensions/EXTENSION_INSTANCE_ID.secret.local.