Instala una extensión de Firebase

Puedes instalar (y administrar) cualquiera de las extensiones oficiales de Firebase con Firebase console, Firebase CLI (una interfaz de línea de comandos) o un SDK generado automáticamente.

Asegúrate de revisar las diferencias en las acciones admitidas para cada método de instalación.


La instalación con un SDK generado automáticamente es una nueva opción para instalar y gestionar extensiones. Con esta opción, usas la CLI para generar automáticamente un SDK de Node para una versión específica de la extensión, que puedes importar como una dependencia ordinaria en tus Cloud Functions de JavaScript o TypeScript.

Este SDK generado automáticamente contiene lo siguiente:

  • Una interfaz que representa los parámetros de la extensión y las declaraciones de tipo para la mayoría de los tipos de parámetros no primitivos.
  • Una función de constructor que inicializa una instancia de la extensión
  • Una clase de extensión que contiene activadores de Eventarc para todos los eventos que emite la extensión.

Una vez que hayas generado un SDK de extensión, toda la configuración de la extensión se realizará en el código.

El uso de esta opción de instalación puede simplificar en gran medida la administración de varias instancias de extensión, en particular en proyectos que contienen Cloud Functions definidas fuera de las extensiones.


Para instalar o administrar extensiones, debes tener asignada una de estas funciones: Propietario o Editor, o bien Administrador de Firebase.

Si quieres instalar una extensión, tu proyecto debe tener el plan Blaze (pago por uso). Aunque la instalación es sin cargo, es posible que se te cobre por el uso de los servicios de Firebase o los servicios de Cloud como Cloud Secret Manager si tu uso sobrepasa el nivel gratuito de los servicios.

Antes de comenzar

  1. Si aún no lo has hecho, agrega Firebase a tu proyecto.

  2. Si aún no lo has hecho, actualiza tu proyecto al plan Blaze (pago por uso).

  3. Instala la versión más reciente de Firebase CLI o actualízala.

  4. Anota el ID del proyecto de Firebase o el alias configurado previamente para el proyecto.

    • ID del proyecto: Ejecuta firebase projects:list desde cualquier ubicación de tu computadora.
    • Alias del proyecto: Ejecuta firebase use desde el directorio local de la app.

Paso 1: Revisa los detalles de la extensión

Este paso es opcional, pero muy recomendable.

Antes de instalar una Firebase Extension, te recomendamos revisar la información detallada sobre la extensión, incluido lo siguiente:

  • El funcionamiento y los detalles de la extensión y las tareas previas a la instalación
  • Información general de identificación y descripción
  • Si se necesita una cuenta de facturación para las tareas de la extensión
  • Los servicios de Google (API) y las funciones de acceso necesarios para el funcionamiento
  • Los recursos creados para la extensión (como las funciones)
  • Descripciones de los parámetros configurables por los usuarios

Para ver la información detallada de una extensión, debes hacer lo siguiente:

  1. Asegúrate de haber configurado tu entorno y seleccionado una extensión.

  2. Ejecuta el comando extension-info desde cualquier ubicación de tu computadora:

    firebase ext:info publisher-id/extension-id

    Los argumentos publisher-id y extension-id son obligatorios, y se pueden encontrar en la página de detalles previos a la instalación de la extensión.

Paso 2: Instala una extensión

Antes de la instalación, revisa las especificaciones básicas de la extensión (como las APIs habilitadas, los recursos creados, el acceso otorgado, etc.) y sus requisitos de facturación.

Antes de continuar, asegúrate de haber configurado tu entorno y seleccionado una extensión.

Inicializa Cloud Functions para Firebase

Si estás comenzando un proyecto nuevo o si tu proyecto aún no usa Cloud Functions para Firebase, ejecuta init functions:

cd your-project
firebase init functions

Elige TypeScript o JavaScript como lenguaje de las funciones.

Si tu proyecto ya tiene inicializado Cloud Functions, asegúrate de usar la versión 5.1.0 o una posterior del paquete firebase-functions:

cd your-project/functions
npm upgrade --save firebase-functions

Si usas ESLint, también te recomendamos que excluyas los SDK generados de tu configuración (.eslintrc.js):

ignorePatterns: [
  "/generated/**/*", // Ignore generated files.
  // ...
],

Genera un SDK de extensión

Desde el directorio local de Firebase, ejecuta el comando ext:sdk:install.

firebase ext:sdk:install publisher-id/extension-id@version

Por ejemplo, para instalar la versión 0.1.34 de la extensión firestore-send-email, haz lo siguiente:

firebase ext:sdk:install firebase/firestore-send-email@0.1.34

publisher-id y extension-id son obligatorios y se pueden encontrar en la página de detalles previos a la instalación de la extensión en extensions.dev. La parte @version es opcional. Si la omites, la herramienta instalará la versión más reciente.

Existen dos opciones que puedes especificar:

  • --force: Realiza lo siguiente sin más confirmación:

    • Genera automáticamente el SDK, incluso si ya se generó uno para la misma extensión y versión.
    • Instala el paquete del SDK generado automáticamente en el proyecto de Node de Cloud Functions.

  • --codebase: Es el nombre de la base de código a la que se agregará el SDK. Si no se especifica, el comando agrega el SDK a la base de código predeterminada, functions.

Con este comando, se crea un paquete de Node que contiene un SDK generado automáticamente para la extensión y se lo agrega a una de las bases de código de Cloud Functions de tu proyecto. En la base de código predeterminada (functions), el SDK se guarda en la siguiente ubicación: 

functions/generated/extensions/publisher-id/extension-id/version

Después de generar el SDK, el comando te preguntará si también quieres instalarlo en tu proyecto de nodos de Cloud Functions. Responde Sí a esta indicación.

Configura instancias de extensiones

Para configurar la extensión, importa el SDK y, para cada instancia de extensión que quieras instalar, llama a la función del constructor y pásale un ID de instancia único del proyecto y los parámetros de configuración que requiere la extensión.

  1. En tu fuente de Cloud Functions, importa el constructor con la sentencia que imprime el comando ext:sdk:install.

    TypeScript

    Por ejemplo, si generaste un SDK para la extensión firestore-send-email, la sentencia import se vería de la siguiente manera:

    import { firestoreSendEmail } from "@firebase-extensions/firebase-firestore-send-email-sdk";

    Si la extensión requiere valores secretos, como contraseñas, también necesitas la función defineSecret del SDK de Cloud Functions:

    import { defineSecret } from "firebase-functions/params";

    JavaScript

    Por ejemplo, si generaste un SDK para la extensión firestore-send-email, la sentencia require se vería de la siguiente manera:

    const { firestoreSendEmail } = require("@firebase-extensions/firebase-firestore-send-email-sdk");

    Si la extensión requiere valores secretos, como contraseñas, también necesitas la función defineSecret del SDK de Cloud Functions:

    const { defineSecret } = require('firebase-functions/params');

  2. Para cada instancia que desees configurar, llama a la función del constructor y exporta el resultado.

    Asigna a cada instancia un ID único que contenga solo letras minúsculas, números y guiones.

    TypeScript

    export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    JavaScript

    exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    Ten en cuenta que los valores secretos se deben especificar con la función defineSecret.

  3. Luego, para implementar las extensiones que configuraste, ejecuta lo siguiente: 

    firebase deploy --only functions --project=projectId-or-alias

    Se aplican todas las opciones habituales de implementación de Cloud Functions. Por ejemplo, para implementar una sola instancia de extensión desde una base de código específica, sigue estos pasos: 

    firebase deploy --only functions:codebase:extension-instance-id --project=projectId-or-alias

Paso 3: Completa la configuración posterior a la instalación

Algunas extensiones tienen pasos opcionales u obligatorios que debes completar antes de usarlas. Encontrarás estas instrucciones en la página de detalles posteriores a la instalación de la extensión en el panel Extensions de Firebase console (el vínculo específico al panel se muestra en la terminal después de la instalación).

También puedes encontrar estas instrucciones en el archivo POSTINSTALL.md incluido en el directorio del código fuente de la extensión.

Crea recursos de Firebase

Si configuraste la extensión para usar los recursos de Firebase (colecciones de Cloud Firestore, rutas de acceso de Realtime Database y buckets de Cloud Storage) que aún no existen, créalos antes de usar la extensión.

Crea controladores de eventos de Eventarc

Algunas extensiones se publican en Eventarc cuando ocurren eventos importantes durante la ejecución. Si una extensión publica eventos, puedes escribir funciones que reaccionen a ellos con tu propia lógica personalizada. Por ejemplo, esto puede ser útil para notificar a los usuarios cuando se completan tareas de larga duración o para procesar posteriormente el resultado de una función de extensión.

Si deseas definir controladores para cualquiera de los eventos que emite la extensión, puedes hacerlo con los métodos de activación de cada instancia:

TypeScript

export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

JavaScript

exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

Debes exportar el controlador de eventos junto con la instancia de la extensión.

Después de definir un controlador de eventos y cada vez que realices cambios en uno, vuelve a implementar la extensión y el controlador.

Instala varias instancias de extensiones

Puedes instalar la misma extensión más de una vez en el mismo proyecto. Cada instancia instalada puede tener su propia configuración personalizada y sus propios recursos de extensión. Identificas cada instancia instalada y haces referencia a ellas mediante el ID de instancia, que es único dentro de tu proyecto.

Llama a la función del constructor del SDK generado automáticamente una vez por cada instancia que deseas instalar y configurar.

Próximos pasos